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USER'S MANUAL STATEMENT 

WARNING: 

This equipment lias been certified to comply witii the limits for a Class B computing device, 
pursuant to subpart J of Part 15 of the Federal Communications Commission's rules, which 
are designed to provide reasonable protection against radio and television interference in a 
residential installation. If not installed properly, in strict accordance with the manufac- 
turer's instructions, it may cause such interference. If you suspect interference, you can 
test this equipment by turning it off and on. If this equipment does cause interference, 
correct it by doing any of the following: 

• Reorient the receiving antenna or AC plug. 

• Change the relative positions of the computer and the 
receiver. 

• Plug the computer into a different outlet so the computer and 
receiver are on different circuits. 

CAUTION: Only peripherals with shield-grounded cables (com- 
puter input-output devices, terminals, printers, etc.), certified to 
comply with Class B limits, can be attached to this computer. 
Operation with non-certified peripherals is likely to result in 
communications interference. 

Your house AC wall receptacle must be a three-pronged type 
(AC ground). If not, contact an electrician to install the proper 
receptacle. If a multi-connector box is used to connect the com- 
puter and peripherals to AC, the ground must be common to all 
units. 

If necessary, consult your Commodore dealer or an experienced radio-television techni- 
cian for additional suggestions. You may find the following FCC booklet helpful: "How to 
Identify and Resolve Radio-TV Interference Problems." The booklet is available from the 
U.S. Government Printing Office. Washington, D.C. 20402, stock no. 004-000-00345-4. 
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Pj How to Use this 
—^ Guide 



This Commodore 128 System Guide is designed to iielp you make 
full use of the advanced capabilities of the Commodore 128 com- 
puter. Here's how to use this Guide: 

Before you read any further in this System Guide, make sure 
you have read the other book packed in the computer carton, 
Introducing The Commodore 128 Personal Computer, 

which contains important information on getting started with 
the Commodore 128. 

If you are primarily interested in using the BASIC language to 
create and run your own programs, you should first read Sec- 
tion 2 of this chapter. This section summarizes the three operat- 
ing modes of the Commodore 128. Then read Chapter II, USING 
C128 MODE. This chapter introduces you to the BASIC pro- 
gramming language as used in both C128 and C64 modes; 
describes the Commodore 128 keyboard; defines some 
advanced commands you can use in both C128 and C64 
modes; shows how to use a number of powerful new BASIC 
commands (including color, graphic and sound commands) that 
are unique to C128 mode; and describes how to use the 80- 
column capabilities available in C128 mode. 

If you want to use BASIC in C64 mode, read Chapter III, USING 
C64 MODE. You can use all the Commodore 64 BASIC 2.0 com- 
mands in C64 mode. Note, however, that the Commodore 128 
BASIC 7.0 language provides many more BASIC commands 
than BASIC 2.0, and the 0128 BASIC commands are more pow- 
erful and easier to use than equivalent BASIC 2.0 commands. 
Remember, you can use C64 mode to run any of the thousands 
of C64 software packages currently available. 

If you want to use CP/M on the Commodore 128, read Chapter 
IV. USING CP/M MODE. This chapter tells you how to start up 
and use CP/M on the Commodore 128. In CP/M mode you can 
choose from thousands of software packages. You can also 
create your own CP/M programs. 

If you want details on the BASIC 7.0 commands, read Chapter V, 
BASIC 7.0 ENCYCLOPEDIA. This chapter gives format and 
usage details on all BASIC 7.0 commands, statements and 
functions. 

If, after reading Chapters I through V, you are looking for addi- 
tional technical information about a particular Commodore 128 
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u 

topic, first check the Appendices to this System Guide. These j I 
appendices contain a wide range of infornnation, such as a ' — 
complete list of BASIC and DOS error messages and a sum- 
mary of disk commands. A Glossary following the Appendices j j 
provides definitions of computing terms. ^ — ' 



For complete technical details about any feature of the Commodore 
128, consult the Commodore 128 Programmer's Reference Guide. 
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The Commodore 128 incorporates many powerful new features, 
including: 

■ A greatly enhanced BASIC language — Commodore BASIC 
7.0 — that provides extensive new commands and 
capabilities 

■ 128K of RAM, which can be expanded to 256 or 640K with 
optional RAM expansion modules 

■ 40- and 80-column video output 

■ Operative with new 1571 fast disk drive 

■ 2 mHz operation 

■ CP/M 3.0 operation 

■ A professional-type keyboard including a full numeric keypad 

■ A built-in machine language monitor 

■ Compatibility with Commodore 64 hardware and software 
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The Commodore 128 Personal Computer is actually three computers 
in one, offering three primary operating modes: 

■ C128 Mode 

■ C64 Mode 

■ CP/M Mode 

Here's a summary of what each mode offers: 

C128 Mode 

In C128 mode, the Commodore 128 Personal Computer provides 
access to 128K of RAM and a powerful extended BASIC language 
known as BASIC 7.0. BASIC 7.0 — which offers over 140 commands, 
statements and functions — has been created by Commodore to 
provide better and easier ways to perform many sophisticated pro- 
gramming tasks, including those involving graphics, animation, 
sound and music. C128 mode also provides both 40- and 80-column 
output capabilities and full use of the 92-key keyboard. The keyboard 
includes a numeric keypad in addition to Escape, Tab, ALPHA LOCK 
and Help keys. A built-in machine language monitor allows you to 
create and debug your own machine language programs. You can 
use these programs in conjunction with a BASIC program. In C128 
mode you can use a number of new peripheral devices from Com- 
modore, including a new fast-serial disk drive, a mouse, and a 40/80- 
column composite video/RGBI monitor. And you can use all standard 
Commodore serial peripherals. 




C64 Mode 

In C64 mode, the Commodore 128 
operates exactly like a Commodore 
64 computer. The Commodore 128 
retains all the capabilities of the com- 
mercially successful C64, thus allow- 
ing you to take full advantage of the 
wide range of available C64 software. 
You also have compatibility with C64 
peripherals, including standard cas- 
sette, joystick, user port and serial devices, as well as C64 compos- 
ite video monitor and TV outputs. 
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Turning On Your 
Commodore 128 



C64 mode provides the BASIC 2.0 language, 40-column output and 
access to 64K of RAM. The main keyboard layout, except for the 
placement of the function keys, is the same as that of a Commodore 
64 computer. All the C64 graphics, color and sound capabilities are 
retained, used exactly as on a Commodore 64. 

CP/M Mode "" 

In CP/M mode, an onboard Z80 microprocessor gives you access to 
the capabilities of Digital Research's CP/M Version 3.0, plus a num- 
ber of new capabilities added by Commodore. The Commodore 
128's CP/M 3.0 package (also known as CP/M Plus) provides 128K of 
RAM, 40- and 80-column output, access to the full keyboard, includ- 
ing the numeric keypad and special keys, and access to the new 
Commodore 1571 fast serial disk drive and the standard peripherals. 
With some exceptions, you will be able to choose from thousands of 
popular software programs — already available, and already proven. 
(Programs created for a specific computer may not run on the Com- 
modore 128. Also, CP/M 3.0 programs on the Commodore 128 may 
run somewhat slower than CP/M systems on high-priced machines.) 

Chapters II, III and IV, which include Sections 3 through 15, tell you 
how to access and use the capabilities of the three powerful and 
versatile operating modes of the Commodore 128 Personal 
Computer. 




Before you turn on your Commodore 128, there are a few things to 
check to make sure that you get started properly. One thing you 
should do before powering up the computer is to make sure the 
40/80 key on the top row of the keyboard is set to match your monitor. 
For example, if you have a 40-column monitor, the 40/80 key should 
be in the up position. If you have an 80-column monitor the 40/80 
key should be depressed. 
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Using Software 



If you are using the Commodore 1902 dual monitor in 40-column 
format, the 40/80 key should be up and the slide switch on the front 
of the monitor should be in the middle position. In 80-column format 
using the 1902 dual monitor, the 40/80 key should be depressed and 
the switch on the front of the monitor should be in the extreme right 
position. 

Regardless of which screen format you are using, check to see that 
both the CAPS LOCK and SHIFT LOCK keys are in the up position. If 
they're not, you may get no picture at all because the monitor switch 
may be set for the opposite screen, or the screen may display unfa- 
miliar symbols. (See Section 5 for a description of all the special keys 
used in C128 mode.) 



If you are using a MAGIC VOICE speech module, insert the module in 
the expansion port and, while holding down the Commodore key 
turn on the power switch. Never plug in any cartridge with the 
power turned on. 

If you experience difficulty getting a cartridge to power-up in C64 
mode, plug in the cartridge with the power off; then hold down the 
Commodore key and turn on the computer. 

If you have the external CP/M 2.2 cartridge marketed for the Com- 
modore 64, do not plug it into the Commodore 128. The Commodore 
128 has a Z80 microprocessor already on-board for CP/M 3.0. If you 
do plug in the CP/M 2.2 cartridge, it can cause unpredictable results. 

If you are using software involving a light pen, plug the light pen into 
Controller Port 1, located on the right side of the C128 near the power 
switch. 
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NOTE: If you are using a Commodore 1902 dual monitor, remember 
to move the video switch on the monitor from COMPOSITE or 
SEPARATED to RGBI when switching from 40-column to 80-column 
display; reverse this step when switching from 80 to 40 columns. Also, 
when changing from CP/M mode to another mode, make sure to 
remove the CP/M operating system diskette from the 1571 disk drive, or 
else upon reset or power-up, the C128 will BOOT CP/M again. 
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The BASIC programming language is a special language that lets you 
communicate with your Commodore 1 28. Using BASIC is one means 
by which you instruct your computer what to do. 

BASIC has its own vocabulary (made up of commands, statements 
and functions) and its own rules of structure (called syntax). You 
can use the BASIC vocabulary and syntax to create a set of instruc- 
tions called a program, which your computer can then perform or 
"run." 

Using BASIC, you can communicate with your Commodore 128 in 
two ways: within a program, or directly (outside a program). 



Direct Mode 

Your Commodore 1 28 is ready to accept BASIC commands in direct 
mode as soon as you turn on the computer. In the direct mode, you 
type commands on the keyboard and enter them into the computer 
by pressing the RETURN key The computer executes all direct 
mode commands immediately after you press the RETURN key 
Most BASIC commands in your Commodore 128 can be used in 
direct mode as well as in a program. 



Program Mode 

In program mode you enter a set of instructions that perform a spe- 
cific task. Each instruction is contained in a sequential program line. 
A statement in a program may be as long as 160 characters; this is 
equivalent to four full screen lines in 40-column format, and two full 
screen lines in 80-column format. 

Once you have typed a program, you can use it immediately by typ- 
ing the RUN command and pressing the RETURN key You can also 
store the program on disk or tape by using the DSAVE (or SAVE) com- 
mand. Then you can recall it from the disk or tape by using the 
DLOAD (or LOAD) command. This command copies the program 
from the disk or tape and places that program in the Commodore 
1 28's memory You can then use or "execute" the program again by 
entering the RUN command. All these commands are explained later 
in this section. Most of the time you will be using your computer with 
programs, including programs you yourself write, and commercially 
available software packages. The only time you operate in direct 
mode is when you are manipulating or editing your programs with 
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commands such as LIST, LOAD, SAVE and RUN. As a rule, the differ- 
ence between direct mode and operation within a program is that 
direct mode commands have no line numbers. 



Using the 
Keyboard 



Shown below is the keyboard of the Commodore 1 28 Personal 
Computer. 




Using BASIC is essentially the same in both C64 and CI 28 modes. 
Most of the keys, and many of the commands you will learn, can be 
used to program BASIC in either mode. The keys that are shaded in 
the figure above can be used in C64 mode. In C128 mode you can 
use all of the keys on the keyboard. 
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Keyboard Character Sets 

The Commodore 128 keyboard offers two different sets of 
characters: 

■ Upper-case letters and graphic characters 

■ Upper- and lower case letters 

In 80-column format, both character sets are available simultane- 
ously. This gives you a total of 51 2 different characters that you can 
display on the screen. In 40 column format you can use only one 
character set at a time. 

When you turn on the Commodore 128 in 40-column format, the key- 
board is normally using the upper-case/graphic character set. This 
means that everything you type is in capital letters. To switch back 
and forth between the two character sets, press the SHIFT key and 
the Cr key (the COMMODORE key) at the same time. To practice 
using the two character sets turn on your computer and press sev- 
eral letters or graphic characters. Then press the SHIFT key and the 
O (Commodore) key Notice how the screen changes to upper- and 
lower-case characters. Press SHIFT and Cf again to return to the 
upper-case and graphic character set. 
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Using the Command Keys 

COMMAND keys are keys that send messages to the computer. 
Some command keys (such as RETURN) are used by themselves. 
Other command keys (such as SHIFT CTRL, Cf and RESTORE) are 
used with other keys. The use of each of the command keys is 
explained below. 



Return 



When you press the RETURN key what you 
have typed is sent to the Commodore 1 28 com- 
puter's memory Pressing the RETURN key also 
moves the cursor (the small flashing rectangle 
that marks where the next character you type 
will appear) to the beginning of the next line. 

At times you may misspell a command or type in 
something the computer does not understand. 
Then, when you press the RETURN key you 
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probably will get a message like SYNTAX 
ERROR on the screen. This is called an "Error 
Message." Appendix A lists the error messages 
and tells how to correct the errors. 

NOTE: In the examples given in this book, the 
following symbol indicates that you must press 
the RETURN key: 



Shift There are two SH I FT keys on the bottom row of 

the keyboard. One key is on the left and the 
other is on the right, just as on a standard type- 
writer keyboard. 

The SHIFT key can be used in three ways: 



i ) 



1 . With the upper/lower-case character set, | i 
the SHIFT key is used like the shift key on a LJ 
regular typewriter. When the SHIFT key is 

held down, it lets you print capital letters or | . 

the top characters on double-character i I 

keys. 

2. The SH I FT key can be used with some of ! I 
the other command keys to perform special ^ — 
functions. 

3. When the keyboard is set for the upper- !, I 

case/graphic character set, you can use the 
SHIFT key to print the graphic symbols or 
characters that appear on the front face of 
certain keys. See the paragraphs entitled 
"Displaying Graphic Characters" at the end 
of this section for more details. 



u 

LJ 



Shift Locic When you press this key down, it locks into |s| 

place. Then, whatever you type will either be a 
capital letter, or the top character of a double- 
character key To release the lock, press down I / 
on the SHIFT LOCK key again. "—^ 
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Moving the In CI 28 mode, you can move the cursor by 

Cursor using either the four arrow l<eys located just 

above the top right of the main keyboard, or the 
two keys labeled CRSR, at the right of the bot- 
tom row of the main keyboard. 
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Using tlie Four Arrow Cursor Keys 

In C128 mode, the cursor can be moved in any 
direction simply by using the arrow key in the 
top row that points in the direction you want to 
move the cursor. (These keys cannot be used in 
C64 mode). 

Using tlie CRSR Iceys 

In both C128 and C64 mode, you can use the 
two keys on the right side of the bottom row of 
the main keyboard to move the cursor: 

• Pressing the CRSR key alone moves the cur- 
sor down. * 

•Pressing the CRSR and SHIFT keys together 
moves the curscfrup- 

• Pressing the CRSR key alone moves the cur- 
sor right- ^ 

• Pressing the C^R and SHIFT keys together 
moves the cursor left. 

You don't have to keep tapping a cursor key to 
move more than one space. Just hold the key 
down and the cursor continues to move until it 
reaches the position you want. 

Notice that when the cursor reaches the right 
side of the screen, it "wraps", or starts again at 
the beginning of the next row. When moving left, 
the cursor will move along the line until it 
reaches the edge of the screen, then it will jump 
up to the end of the preceding line. 
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You should try to become very familiar with the 

cursor keys, because moving the cursor makes ^ { 

your programming much easier. With a little 
practice you will find that you can move the cur- 
sor almost without thinking about it. 



Inst/Del This is a dual purpose key INST stands for 

INSerT and DEL for DELete. 



Then, while you hold down the SHIFT key press 
the INST/DEL key until you have enough space 
to add the missing characters: 

WHILE ■ U WERE OUT 

Notice that INST doesn't move the cursor; it just 
adds space between the cursor and the charac- 
ter to its right. To make the correction, simply 
type in the missing "Y" and "O", like this: 

WHILE YOU WERE OUT 
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Inserting Characters |^ j 

You must use the SHIFT key with the INST/DEL 

key when you want to insert characters in a line. i i 

Suppose you left some characters out of a line, ^ — ' 
like this: 

WHILE U WERE OUT [J 

To insert the missing characters, first use the 
cursor keys to move the cursor back to the 
error, like this: 

WHILEHWERE OUT 
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Deleting Characters 

When you press the DEL key the cursor moves 

one space to the left and erases the character M 

that is there. This means that when you want to 

delete something, you move the cursor just to 

the right of the character you want to DELete. I j 

Suppose you have made a mistake in typing, like 

this: 

PRINT "ERROER" U 
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Control 



Run/Stop 



You wanted to type the word ERROR, not 
ERROER. To delete the incorrect E that pre- 
cedes the final R, position the cursor in the 
space where the final R is located. When you 
press the DEL key the character to the right of 
the cursor (the R) autonnatically nnoves over one 
space to the left. You now have the correct 
wording like this: 

PRINT "ERROR" 



Using INSerT and DELete Together 

You can use the INSerT and DELete functions 
together to fix incorrect characters. First, move 
the cursor to the incorrect characters and press 
the INST/DEL key by itself to delete the charac- 
ters. Next, press the SHIFT key and the INST/ 
DEL key together to add any necessary space. 
Then type in the corrections. You can also type 
directly on top of undesired characters, then use 
INST to add any needed space. 

The Control key is used with other keys to do 
special tasks called control functions. To per- 
form a control function, hold down the Control 
key while you press some other key Control 
functions are often used in prepackaged soft- 
ware such as a word processing system. 

One control function that is used often is setting 
the character and cursor color. To select a color, 
hold down the CTRL key while you press a num- 
ber key (1 through 8), on the top row of the key- 
board. There are eight more colors available to 
you; these can be selected with the & key as 
explained later. 

This is a dual function key Under certain condi- 
tions you can use the RUN function of this key 
by pressing the SHIFT and RUN/STOP together. 
It is also possible to use the STOP function of 
this key to halt a program or a printout by press- 
ing this key while the program is running. How- 
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ever, in most prepackaged programs, the STOP 
function of the RUN/STOP key is intentionally 
disabled (made unusable). This is done to pre- 
vent the user from trying to stop a program that 
is running before it reaches its normal end point. 
If the user were able to stop the program, valu- 
able data could be lost. 

Restore The RESTORE key is used with the RUN/STOP 

key to return the computer to its standard condi- 
tion. To do this, hold down the RUN/STOP key 
and press RESTORE. 

Most prepackaged programs disable the 
RESTORE key for the same reason they disable 
the STOP function of the RUN/STOP key: to pre- 
vent losing valuable data. 

CLR/Home CLR stands for CLeaR. HOME refers to the 

upper-left corner of the screen, which is called 
the HOME position. If you press this key by itself 
the cursor returns to the HOME position. When 
you use the SHIFT key with the CLR/HOME key 
the screen CLeaRs and the cursor returns to the 
HOME position. 

Commodore Key The O key (known as the COMMODORE key) 
{&) has a number of functions, including the follow- 

ing ones: 

1 . The C- key lets you switch back and forth 
between the upper/lower-case character 
set (which displays the letters and charac- 
ters on the top of the keys), and the upper- 
case/graphic display character set (which 
displays capital letters and the graphics 
symbols on the front face of the keys). To 
switch modes, press the fr key and the 
SHIFT key at the same time. 

2. The C- key also lets you use a second set of 
eight colors for the cursor. To get these col- 
ors, you hold down the & key while you 
press a number key (1 through 8) in the top 
row. 
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If you hold down the O key while turning on 
the connputer, you can immediately access 
C64 mode. 



Function Keys 



The four keys located above the numeric keypad (marked F1 , F3, F5 
and F7 on the top and F2, F4, F6 and F8 on the front) are called func- 
tion Iceys. In CI 28 and C64 modes, you can program the function 
keys. (See the KEY command descriptions in Section 5 of Chapter II 
and in Chapter V, BASIC 7.0 ENCYCLOPEDIA). These keys are also 
often used by prepackaged software to allow you to perform a task 
with a single keystroke. 
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Displaying Graphic Cliaracters 

To display the graphic symbol on the right front face of a key hold 
down the SHIFT key while you press the key that has the graphic 
character you want to print. You can display the right side graphic 
characters only when the keyboard is in the upper-case/graphics 
character set (the normal character set usually available at power- 
up). 

To display the graphic character on the left front face of a key hold 
down the C- key while you press the key that has the graphic charac- 
ter you want. You can display the left graphic character while the 
keyboard is in either character set. 



I \ 



Rules for Typing BASIC Language Programs 

You can type and use BASIC language programs even without know- 
ing BASIC. You must type carefully however, because a typing error 
may cause the computer to reject your information. The following 
guidelines will help minimize errors when typing or copying a pro- 
gram listing. 

1 . Spacing between words is not critical; e.g., typing 

FORT = 1 T01 is the same as typing FOR T = 1 TO 1 0. However, 
a BASIC keyword itself must not be broken up by spaces. (See 
the BASIC 7.0 Encyclopedia in Chapter V for a list of BASIC key- 
words). 

2. Any characters can be typed inside quotation marks. Some char- 
acters have special functions when placed inside quotation 
marks. These functions are explained later in this Guide. 
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Getting Started— 
The PRINT 
Command 



3. Be careful with punctuation marks. Commas, colons and semi- 
colons also have special properties, explained later in this 
section. 

4. Always pres s the RETURN key (indicated in this Guide by 

nL i Uh l sl= ) after completing a numbered line. 

5. Never type more than 1 60 characters in a program line. Remem- 
ber, this is the same as four full screen lines in 40-column format, 
or two full screen lines in 80-column format. See Section 8 for 
more details on 40- and 80-column formats. 

6. Distinguish clearly between the letter I and the numeral 1 and 
between the letter and the numeral 0. 

7. The computer ignores anything following the letters REM on a 
program line. REM stands for REMark. You can use the REM 
statement to put comments in your program that tell anyone list- 
ing the program what is happening at a specific point. 

Follow these guidelines when you type the examples and programs 
shown in this section. 



The PRINT command tells the computer to display information on the 
screen. You can print both numbers and text (letters), but there are 
special rules for each case, described in the following paragraphs. 

Printing Numbers 

To print numbers, use the PRINT command followed by the num- 
ber(s) you want to print. Try typing this on your Commodore 1 28: 

PRINT 5 

Then press the RETURN key Notice the number 5 is now displayed 
on the screen. 

Now type this and press RETURN: 

PRINT 5,6 

In this PRINT command, the comma tells the Commodore 1 28 that 
you want to print more than one number. When the computer finds 
commas in a string of numbers in a PRINT statement, each number 
that follows a comma is printed starting in either the 11 th, 21 st or 
31 St column on the screen, depending on the length of each number. 
If the previous number has more than 7 digits, the following number 
is moved to the next starting position, 1 columns to the right. The 
CI 28 always leaves at least 3 spaces between numbers which are 
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separated by a comma. If you don't want all the extra spaces, use a 
semicolon (;) in your PRINT statement instead of a comma. The semi- 
colon tells the computer not to add any spaces between strings and 
numeric variables and numeric constants. Numbers and numeric 
variables are printed with either a leading space or a minus sign, and 
a trailing space. Omitting a semicolon, a comma, or any separators 
acts the same as a semi-colon. Type these examples and see what 
happens: 



PRINT 5;6 

PRINT 100;200;300;400;500 

Using the Question IMaric to Abbreviate the PRINT 
Command 

You can use a question mark (?) as an abbreviation for the PRINT 
command. Many of the examples in this section use the ? symbol in 
place of the word PRINT In fact, most of the BASIC commands can 
be abbreviated. However, when you LIST a program, the keyword 
appears in the long version. The abbreviations for BASIC commands 
can be found in Appendix K of this Guide. 

Printing Text 

Now that you know how to print numbers, it's time to learn how to 
print text. It's actually very simple. Any words or characters you want 
to display are typed on the screen, with a quote symbol at each end 
of the string of characters. String is the BASIC name for any set of 
characters surrounded by quotes. The quote character is obtained 
by pressing SHIFT and the numeral 2 key on the top row of the key- 
board (not the 2 in the numeric keypad). Try these examples: 



? "COMMODORE 128" 

Notice that when you press RETURN, the computer displays the 
characters within the quotes on the screen. Also note that the sec- 
ond example did not calculate 4*5 since it was treated as a string 
and not a mathematical calculation. If you want to calculate the 
result 4*5, use the following command: 

?4*5 



You can PRINT any string you want by using the PRINT command 
and surrounding the printed characters with quotes. You can com- 
bine text and calculations in a single PRINT command like this: 



9 "4*5- "4*5 i 
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See how the computer PRINTS the characters in quotes, makes the 
calculation and PRINTS the result. It doesn't matter whether the text 
or calculation comes first. In fact, you can use both several times in 
one PRINT command. Type the following statement: 

? 4*(2 + 3)" is the same as "4*5 RETURN 

Notice that even spaces inside the quotation marks are printed on 
the screen. Type: 



9 " 



OVER HERE" 



Printing in Different Colors 

The Commodore 1 28 is capable of displaying 1 6 different colors on 
the screen. You can change colors easily All you do is hold down the 
CTRL key and press a numbered key between 1 and 8 on the top row 
of the main keyboard. Notice that the cursor changes color accord- 
ing to the numbered key you pressed. All the succeeding characters 
are displayed in the color you selected. Hold down the Commodore 
key and press a numbered key between 1 and 8, and eight additional 
colors are displayed on the screen. 

Table 3-1 lists the colors available on in CI 28 mode, for both 40- and 
80-column screen formats. 
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Color Code 


Color 
Black 


Color Code 
9 


Color 




1 


Orange 


u 


2 


White 


10 


Brown 


3 


Red 


11 


Light Red 




4 


Cyan 


12 


Dark Gray 




5 


Purple 


13 


Medium Gray 


6 


Green 


14 


Light Green 




7 


Blue 


15 


Light Blue 


1 1 


8 


Yellow 


16 


Light Gray 
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Color Numbers i 


n 40-Column Format 




Color Code 


Color 


Color Code 
9 


Color 


] 


1 


Black 


Dark Purple 




2 


White 


10 


Dark Yellow 


\ 


3 


Dark Red 


11 


Light Red 


\ 


4 


Light Cyan 


12 


Dark Cyan 




5 


Light Purple 


13 


Medium Gray 


\ J 


6 


Dark Green 


14 


Light Green 


! 1 


7 


Dark Blue 


15 


Light Blue 




8 


Light Yellow 


16 


Light Gray 
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Color Numbers 


in 80-Co!umn Format 
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Beginning to 
Program 



Using tlie Cursor Keys inside Quotes witii tlie PRINT 
Command 

When you type the cursor keys inside quotation nnarks, graphic char- 
acters are shown on the screen to represent the keys. These charac- 
ters will NOT be printed on the screen when you press RETURN. Try 
typing a question mark (?), open quotes (SHIFTed 2 key); then press 
either of the down cursor keys 1 times, enter the words "DOWN 
HERE", and close the quotes. The line should look like this: 



9 j( 



QQQQQQQQQQIlIS 



WN HERE" 



Now press RETURN. The Commodore 1 28 prints 1 blank lines, and 
on the eleventh line, it prints "DOWN HERE". As this example 
shows, you can tell the computer to print anywhere on your screen 
by using the cursor control keys inside quotation marks. 



So far most of the commands we have discussed have been per- 
formed in DIRECT mode. That is, the command was executed as 
soon as the RETURN key was pressed. However, most BASIC com- 
mands and functions can also be used in programs. 



Wliat a Program is 

A program is just a set of numbered BASIC instructions that tells your 
computer what you want it to do. These numbered instructions are 
referred to as statements or lines- 



Line Numbers 

The lines of a program are numbered so that the computer knows in 
what order you want them executed or RUN. The computer executes 
the program lines in numerical order, unless the program instructs 
otherwise. You can use any whole number from to 63999 for a line 
number. Never use a comma in a line number. 

Many of the commands you have learned to use in DIRECT mode 
can be easily made into program statements. For example, type this: 

10 ? "COMMODORE 128" 
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Notice the computer did not display COMMODORE 128wlienyou , > 

pressed RETURN, as it would do if you were using the PRINT com- 1 ! 

mand in DIRECT mode. This is because the number, 1 0, that comes 

before the PRI NT symbol (?) tells the computer that you are entering c i 

a BASIC program. The computer just stores the numbered statement I i 

and waits for the next input from you. 

Now type RUN and press RETURN. The computer prints the words I ) 

COMMODORE 1 28. This is not the same as using the PRINT com- 
mand in DIRECT mode. What has happened here is that YOU HAVE . > 
JUST WRITTEN AND RUN YOUR FIRST BASIC PROGRAM as small LJ 
as it may seem. The program is still in the computer's memory so 
you can run it as many times as you want. 



Type LIST and press RETURN. The 01 28 responds with: 
10 PRINT "COMMODORE 128" 
READY 



u 



Viewing Your Program— Tiie LIST Command 

Your one-line program is still in the C1 28 memory Now clear the 

screen by pressing the SHIFT and CLR/HOME keys together. The 

screen is empty At this point you may want to see the program list- } [ 

ing to be sure it is still in memory The BASIC language is equipped ^ — ' 

with a command that lets you do just this — the LIST command. 

u 
u 



Anytime you want to see all the lines in your program, type LIST This . 

is especially helpful if you make changes, because you can check to 1 1 

be sure the new lines have been registered in the computer's mem- 
ory In response to the command, the computer displays the 

changed version of the line, lines, or program. Here are the rules for ' | 

using the LIST command. (Insert the line number you wish to see in 
place of the N.) 

—To see line N only type LIST N and press RETURN. 



u 



— To see from line N to the end of the program, type LIST N- and ^ ■ 
press RETURN. U 

—To see the lines from the beginning of the program to line N, 
type LIST-N and press RETURN. \J 

—To see from line N1 to line N2 inclusive, type LIST N1-N2 and 
press RETURN. 
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A Simple Loop— The GOTO Statement 

The line numbers in a program have another purpose besides put- 
ting your commands in the proper order for the computer. They 
serve as a reference for the computer in case you want to execute 
the command in that line repetitively in your program. You use the 
GOTO command to tell the computer to go to a line and execute the 
command(s) in it. Now type: 

20 GOTO 10 

When you press RETURN after typing line 20, you add it to your pro- 
gram in the computer's memory 

Notice that we numbered the first line 1 and the second line 20. It is 
very helpful to number program lines in increments of 1 (that is, 1 0, 
20, 30, 40, etc.) in case you want to go back and add lines in 
between later on. You can number such added lines by fives (1 5, 25 
. . . ) ones (1,2... ) — in fact, by any whole number — to keep the lines 
in the proper order. (See the RENUMBER and AUTO commands in 
the BASIC Encyclopedia.) 

Type RUN and press RETURN, and watch the words COMMODORE 
128 move down your screen. To stop the message from printing on 
the screen, press the RUN/STOP key on the left side of your 
keyboard. 

The two lines that you have typed make up a simple program that 
repeats itself endlessly because the second line keeps referring the 
computer back to the first line. The program will continue indefinitely 
unless you stop it or turn off the computer. 



Now type LIST i 



. The screen should say: 



10 PRINT "COMMODORE 128" 

20 GOTO 10 

READY. 

Your program is still in memory You can RUN it again if you want to. 
This is an important difference between PROGRAM mode and 
DIRECT mode. Once a command is executed in DIRECT mode, it is 
no longer in the computer's memory Notice that even though you 
used the ? symbol for the PRINT statement, your computer has con- 
verted it into the full command. This happens when you LIST any 
command you have abbreviated in a program. 
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Clearing the Computer's Memory— The NEW Command 

Anytime you want to start all over again or erase a BASIC program in 
the computer's memory, just type NEW and press RETURN. This 
command clears out the computer's BASIC memory the area where 
programs are stored. 



Using Color in a Program 

To select color within a program, you must include the color selec- 
tion information within a PRINT statement. For example, clear your 
computer's memory by typing NEW and pressing RETURN, then 
type the following, being sure to leave space between each letter: 

10 PRINT "SPECTRUM" nCTURM 

Now type line 1 again but this time hold down the CTRL key and 
press the 1 key directly after entering the first set of quote marks. 
Release the CTRL key and type the "S". Now hold down the CTRL 
again and press the 2 key Release the CTRL key and type the "P". 
Next hold down the CTRL again and press the 3 key. Continue this 
process until you have typed all the letters in the word SPECTRUM 
and selected a color between each letter. Press the SHIFT and the 2 
keys to type a set of closing quotation marks and press the RETURN 
key Now type RUN and press the RETURN key The computer dis- 
plays the word SPECTRUM with each letter in a different color. Now 
type LIST and press the RETURN key Notice the graphic characters 
that appear in the PRINT statement in line 1 0. These characters tell 
the computer what color you want for each printed letter. Note that 
these graphic characters do not appear when the Commodore 128 
PRINTS the word SPECTRUM in different colors. 

The color selection characters, known as control characters, in the 
PRINT statement in line 1 tell the Commodore 1 28 to change col- 
ors. The computer then prints the characters that follow in the new 
color until another color selection character is encountered. While 
characters enclosed in quotation marks are usually PRINTed exactly 
as they appear, control characters are only displayed within a pro- 
gram LISTing. 
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Editing Your 
Program 
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The following paragraphs will help you to type in your programs and 
nnake corrections and additions to them. 



Erasing a Line from a Program 

Use the LIST command to display the program you typed previously 
Now type 1 and press RETURN. You just erased line 1 from the 
program. LIST your program and see for yourself. If the old line 1 is 
still on the screen, move the cursor up so that it is blinking anywhere 
on that line. Now, if you press RETURN, line 10 is back in the comput- 
er's memory 



Dupiicating a Line 

Hold down the SHIFT key and press the CLR/HOME key on the upper 
right side of your keyboard. This will clear your screen. Now LIST 
your program. Move the cursor up again so that it is blinking on the 
"0" in the line numbered 1 0. Now type a 5 and press RETURN. You 
have just duplicated (i.e., copied) line 1 0. The duplicate line is num- 
bered 1 5. Type LIST and press RETURN to see the program with the 
duplicated lines. 



Replacing a Line 

You can replace a whole line by typing in the old line number fol- 
lowed by the text of the new line, then pressing RETURN. The old 
version of the line will be erased from memory and replaced by the 
new line as soon as you press RETURN. 



Clianging a Line 

Suppose you want to add something in the middle of a line. Simply 
move the cursor to the character or space that immediately follows 
the spot where you want to insert the new material. Then hold down 
the SHIFT key and the INST/DEL key together until there is enough 
space to insert your new characters. 

Try this example. Clear the computer's memory by typing NEW and 
pressing RETURN. Then type: 

10 ? "MY 128 IS GREAT" 
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Mathematical 
Operations 



Let's say that you want to add the word COMMODORE in front of the 
nunnber 1 28. Just move the cursor so that it is blinking on the "1 " in 
1 28. Hold down the SHIFT and INST/DEL keys until you have enough 
room to type in COMMODORE (don't forget to leave enough room for 
a space after the E). Then type in the word COMMODORE. 

If you want to delete something in a line (including extra blank 
spaces), move the cursor to the character following the material you 
want to remove. Then hold down the INST/DEL key by itself. The cur- 
sor will move to the left, and characters or spaces will be deleted as 
long as you hold down the INST/DEL key 



You can use the PRINT command to perform calculations like addi- 
tion, subtraction, multiplication, division and exponentiation. You 
type the calculation after the PRINT command. 



Addition and Subtraction 

Try typing these examples: 

PRINT 6 + 4 i 

PRINT 50-20 

PRINT10 + 15-5 

PRINT 75- 100 ~ 

PRINT 30 + 40,55-25 

PRINT30 + 40;55-25 

Notice that the fourth calculation (75-100) resulted in a negative 
number. Also notice that you can tell the computer to make more 
than one calculation with a single PRINT command. You can use 
either a comma or a semicolon in your command, depending on 
whether or not you want spaces separating your results. 

■Multiplication and Division 

Find the asterisk key (*) on the right side of your keyboard. This is the 
symbol that the Commodore 1 28 uses for multiplication. The slash (/) 
key located next to the right SHIFT key is used for division. 
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Try these examples: 
PRINT 5*3 
PRINT 100/2 
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Exponentiation 

Exponentiation means to raise a number to a power. Tlie up arrow 
key (t), located next to the asterisk on your keyboard, is used for 
exponentiation. If you want to raise a number to a power, use the 
PRINT command, followed by the number, the up arrow and the 
power, in that order. For example, to find out what 3 squared is, type: 

PRINT 3t2 \ 
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Order of Operations 

You have seen how you can combine addition and subtraction in the 
same PRINT command. If you combine multiplication or division with 
addition or subtraction operations, you may not get the result you 
expect. For example, type: 

PRINT 4 + 6/2 HL I UHM 

If you assumed you were dividing 10 by 2, you were probably sur- 
prised when the computer responded with the answer 7. The reason 
you got this answer is that multiplication and division operations are 
performed by the computer before addition or subtraction. Multipli- 
cation and division are said to take precedence over addition and 
subtraction. It doesn't matter in what order you type the operation. In 
computing, the order in which mathematical operations are per- 
formed is known as the order of operations. 

Exponentiation, or raising a number to a power, takes precedence 
over the other four mathematical operations. For example, if you 
type: 

PRINT 16/4t2 nnim M 

the Commodore 128 responds with a 1 because it squares the 4 
before it divides 16. 
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Using Parentheses to Define tlie Order of Operations 

You can tell the Commodore 1 28 which mathematical operation you 
want performed first by enclosing that operation in parentheses in 
the PRINT command. For instance, in the first example above, if you 
want to tell the computer to add before dividing, type: 



PRINT(4 + 6)/2 

This gives you the desired answer, 5. 

If you want the computer to divide before squaring in the second 
example, type: 



PRINT (16/4)t2i 

Now you have the expected answer, 16. 

If you don't use parentheses, the computer performs the calcula- 
tions according to the above rules. When all operations in a calcula- 
tion have equal precedence, they are performed from left to right. 
For example, type: 



PRINT 4*5/10*6: 

Since the operations in this example are performed in order from left 
to right, the result is 12 (4*5 = 20 . . . 20/10 = 2 ... 2*6 = 12). If you 
want to divide 4*5 by 1 0*6 you type: 

PRINT (4*5)/(10*6) m llllfM 

The answer is now .333333333. 



Constants 

Constants are numeric values that are permanent: that is, they do 
not change in value over the course of an equation or program. For 
example, the number 3 is a constant, as is any number. This state- 
ment illustrates how your computer uses constants: 

10 PRINT 3 

No matter how many times you execute this line, the answer will 
always be 3. 
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Variables 

Variables are values that can change over the course of an equation 
or progrann statennent. There is a part of the connputer's BASIC nnem- 
ory that is reserved for the characters (numbers, letters and sym- 
bols) you use in your program. Think of this memory as a number of 
storage compartments in the computer that store information about 
your program; this part of the computer's memory is referred to as 
variable storage. Type in this program: 

10X = 5 
20 ?X 

Now RUN the program and see how the computer prints a 5 on your 
screen. You told the computer in line 1 that the letter X will repre- 
sent the number 5 for the remainder of the program. The letter X is 
called a variable, because the value of X varies depending on the 
value to the right of the equals sign. We call this an assignment state- 
ment because now there is a storage compartment labeled X in the 
computer's memory and the number 5 has been assigned to it. The 
= sign tells the computer that whatever comes to the right of it will 
be assigned to a storage compartment (a memory location) labeled 
with the letter X to the left of the equals sign. 

The variable name on the left side of the = sign can be either one or 
two letters, or one letter and one number (the letter MUST come 
first). The names can be longer, but the computer only looks at the 
first two characters. This means the names PA and PART would refer 
to the same storage compartment. Also, the words used for BASIC 
commands (LOAD, RUN, LIST, etc.) or functions (INT, ABS, SQR, etc.) 
cannot be used as names in your programs. Refer to the BASIC 
Encyclopedia in Chapter 5 if you have any questions about whether a 
variable name is a BASIC keyword. Notice that the = in assignment 
statements is not the same as the mathematical symbol meaning 
"equals", but rather means allocate a variable (storage compart- 
ment) and assign a value to it. 

In the sample program you just typed, the value of the variable X 
remains at 5 throughout. You can put calculations to the right of the 
= sign to assign the result to a variable. You can mix text with con- 
stants in a PRINT statement to identify them. Type NEW and press 
RETURN to clear the Commodore 1 28's memory; then try this 
program: 

10 A = 3*100 

^0B = 3*200 

30 ?"A IS EQUAL TO "A 

40 ?"B IS EQUAL TO "B 
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Now LIST the program and trace the steps taken by the computer. 
First, it assigns the value to the right of the = sign in line 10 to the 
letter A. It does the same thing in line 20 for the letter B. Next, it 
prints the messages in lines 30 and 40 that give you the values of A 
and B. Finally it assigns new values to A and B in lines 50 and 60. 
The old values are replaced and cannot be recovered unless the 
computer executes lines 10 and 20 again. When the computer is 
sent to line 30 to begin printing the values of A and B again, it prints 
the new values calculated in lines 50 and 60. Lines 50 and 60 reas- 
sign the same values to A and B and line 70 sends the computer 
back to line 30. This is called an endless loop, because lines 30 
through 70 are executed over and over again until you press the 
RUN/STOP key to halt the program. Other methods of looping are 
discussed later in this and the following two sections. 



Strings 



u 



Now there are two variables, labeled A and B, in the computer's 

memory containing the numbers 300 and 600 respectively If, later in 

the program, you want to change the value of a variable, just put 

another assignment statement in the program. Add these lines to the ^ i 

program above and RUN it again. ' — 1 

50 A = 900*30/10 

60 8 = 95 + 32 + 128 M 

70 GOTO 30 

You'll have to press the STOP key to halt the program. 
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A string is a character or group of characters enclosed in quotes. 
These characters are stored in the computer's memory as a variable 
in much the same way numeric variables are stored. You can also ] I 

use variable names to represent strings, just as you use them to rep- 
resent numbers. When you put the dollar sign ($) after the string vari- 
able name, it tells the computer that the name is for a string variable, ] I 
and not a numeric variable. 

Type NEW and press RETURN to clear your computer's memory j j 

then type in the program below: 

10 A$ = "COMMODORE" . , 

20X = 128 LJ 

30 B$ = " COMPUTER" 

40Y = 1 

50 ? "THE "A$;X;B$" IS NUMBER "Y 
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Sample Program 



Storing and 
Reusing Your 
Programs 



See how you can print numeric and string variables in tine same 
statement? Try experimenting with variables in your own short 
programs. 

You can print the value of a variable in DIRECT mode, after the pro- 
gram has been RUN. Type ?A$;B$;X;Y after running the program 
above and see that those four variable values are still in the comput- 
er's memory 

If you want to clear this area of BASIC memory but still leave your 
program intact, use the CLR command. Just type CLR < RETURN) 
and all constants, variables and strings are erased. But when you 
type LIST, you can see the program is still in memory The NEW com- 
mand discussed earlier erases both the program and the variables. 



Here is a sample program incorporating many of the techniques and 
commands discussed in this section. 

This program calculates the average of three numbers (X, Y and Z) 
and prints their values and their averages on the screen. You can 
edit the program and change the assignments in lines 1 through 30 
to change the values of the variables. Line 40 adds the variables and 
divides by 3 to get the average. Note the use of parentheses to tell 
the computer to add the numbers before it divides. 

TIP: Whenever you are using more than one set of parentheses 
in a statement, it's a good idea to count the number of left 
parentheses and right parentheses to make sure they are 
equal. 

10X = 46 

20Y = 72 

30Z = 114 

40A = {X-}-Y + Z)/3 

60 ?"THE AVERAGE OF"X;Y;"AND "Z;"IS"A; 

90 END 



Once you have created your program, you will probably want to store 
it permanently so you will be able to recall and use it at some later 
time. To do this, you'll need either a Commodore disk drive or the 
Commodore 1 530 Datassette. 
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You will learn several commands that let you communicate between 
your computer and your disk drive or Datassette. These commands 
are constructed with the use of a command word followed by several 
parameters. Parameters are numbers, letters, words or symbols in a 
command that supply specific information to the computer, such as 
a filename, or a numeric variable that specifies a device number. 
Each command may have several parameters. For example, the 
parameters of the disk format command include a name for the disk 
and an identifying number or code, plus several other parameters. 
Parameters are used in almost every BASIC command; some are 
variables which change and others are constants. These are the 
parameters that supply disk information to the CI 28 and disk drive: 

Disk Handling Parameters 

disk name — arbitrary 1 6 character identifying name 

you supply 

file name — arbitrary 1 6 character identifying name 

you supply 

i.d. — arbitrary two-character identifier you 

supply 

drive number — must use for a single disk drive, or 1 
in a dual drive. 

device number — a preassigned number for a peripheral 
device. For example, the device num- 
ber for a Commodore disk drive is 
usually 8. 



Formatting a Disk— The HEADER Command 

To store programs on a new (or blank) disk, you must first prepare the 
disk to receive data. This is called "formatting" the disk. NOTE: 
Make sure you turn on the disk drive before inserting any disk. 

The formatting process divides the disk into sections called tracks 
and sectors. A table of contents, called a directory is created. Each 
time you store a program on disk, the name you assign to that pro- 
gram will be added to the directory 

The Commodore 1 28 has two kinds of formatting commands. One 
can be used only in CI 28 mode, and one can be used in both C64 
and C1 28 mode. The following paragraphs describe CI 28 mode 
format commands here. See Chapter III on C64 mode for more infor- 
mation about C64 programming and disk handling. 
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The command that formats a diskette is called the HEADER com- 
mand. It has a long form and a short form. To format a blank (new) 
disk, you MUST use the long form as follows: 

HEADER "diskname", li.d.[,Ddrive number] [,[ON]U device number] 

After the word HEADER, you type a name of your choice for the disk, 
within quotes. You can choose any name with up to 16 characters. 
You should choose disk names that help you identify what will be 
stored on the disk. 

Follow the diskname with a comma and the letter "I". Now a two 
character i.d., followed by a comma. Your disk i.d. does not have to 
be numbers; you can also choose letters. You may want to develop a 
consecutive coding system for your disks, such as A1 , A2, B1 , B2. 

If you have one single disk drive, just press RETURN at this point 
since the Commodore 1 28 automatically assumes the drive number 
is and the device number is 8. You can specify these parameters if 
you have more than one drive or a dual drive. 

The next parameter in the command selects the drive number. Press 
the "D" key and if you have a single disk drive, press the zero key 
followed by a comma. Dual drives are labeled and 1 . The device 
number parameter starts with the letter U so press the "U" key fol- 
lowed by the preassigned device number for a Commodore disk 
drive which is 8. 

Here is an example of the long form of the HEADER command: 

HEADER"RECS",IA1,D0,U8 RETURN 

This command formats the diskette, calling the directory RECS, the 
i.d. number A1 , on drive 0, unit 8. 

The default values for disk drive (0) and device number (8) will be 
used if none are supplied. This is an acceptable long form of the 
HEADER command: 

HEADER "MYDISK", 123 Hh l UHN 

The HEADER command can also be used to erase all data from a 
used disk, so the disk can be reused as if it were a brand new disk. 
Be careful that you don't erase a disk that contains data you may 
want someday 
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The quick form of the HEADER command can be used if the disk 
was previously formatted with the long form of the HEADER 
command. 

The quick form clears the directory, gives it a new name, but keeps 
the same i.d. as was previously used. Here is what the quick 
HEADER might look like: 

HEADER "NEWPROGS" 
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SAVEing on Disk 

In CI 28 mode, you can store your program on disk by using either of . i 

the following commands: LJ 

DSAVE"PROGRAM NAME" umiUM 

SAVE"PROGRAM NAME",8 '" TiinM jj 

Either command can be used. Remember that the character 

sequence "DSAVE" can be displayed on the screen by pressing the ^ , 

function key labeled F5, or you can type the sequence yourself. The 1 1 

program name can be any name you choose, up to 16 characters 

long. Be sure to enclose the program name in quotes. You cannot . . 

put two programs with the same name on the same disk. If you do, ! ! 

the second program will not be accepted; the disk will retain the first 

one. In the second example, the 8 indicates that you are saving your ^ , 

program on device number 8. You do not need the 8 with DSAVE, 1 1 

because the computer automatically assumes you are using device 

number 8. . . 

SAVEing on Cassette . I 

If you are using a Datassette to store your program, insert a blank 
tape in the recorder, rewind the tape if necessary and type: 

SAVE "PROGRAM NAME" H H^mM U 

You must type the word SAVE, followed by the program name. The 

program name can be any name you choose up to 1 6 characters. j j 

NOTE: The screen will go blank while the program is being 

SAVEd, but returns to normal when the process is completed. ] i 

Unlike disk, you can save two programs to tape under the same 

name. However when you load it back into the computer, the first j I 

program sequentially on the tape will be loaded, so avoid giving pro- ' — ^ 
grams the same name. 

u 
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Once a program has been SAVEd, you can LOAD it back into tine 
computer's memory and RUN it anytime you wish. 



LOADing from Disk 

Loading a program simply copies the contents of the program from 
the disk into the computer's memory If a BASIC program was 
already in memory before you issued the LOAD command, it is 
erased. 

To load your BASIC program from a disk, use either of the following 
commands in CI 28 mode: 



DLOAD"PROGRAM NAME" 

LOAD"PROGRAM NAME",8 i " m u M 

Remember, in CI 28 mode you can use the F2 function key (which 
you activate by pressing SHIFT and F1) to display the sequence 
DLOAD", or you can type the letters yourself. In the second exam- 
ple, the 8 indicates to the computer that you are loading from device 
number 8. Again, like DSAVE, DLOAD assumes the disk-drive device 
number is 8. Be careful to type the program name exactly as you 
typed it when SAVEing the program, or the computer will respond 
"FILE NOT FOUND." 

Once the program is loaded, type RUN to execute. The Commodore 
128 has a special form of the RUN command used to LOAD and 
RUN the program in CI 28 mode with one command. Type RUN, fol- 
lowed by the name of the program (also known as the filename) in 
quotes: 

RUN"MYPROG" 



LOADing from Cassette 

To LOAD your program from cassette tape, type: 
LOAD "PROGRAM NAME" IlLI U l iM 

If you do not know the name of the program, you can type: 

and the next program on the tape will be found. While the Datassette 
is searching for the program the screen is blank. When the program 
is found, the screen displays: 

FOUND PROGRAM NAME 
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To actually load the program, you then press the Commodore key 

You can use the counter on the Datassette to identify the starting 
position of the programs. Then, when you want to retrieve a pro- 
gram, simply wind the tape forward from 000 to the program's start 
location, and type: 

In this case you don't have to specify the PROGRAM NAME; your 
program will load automatically because it is the next program on 
the tape. 



Other Disk-Related Commands 



Verifying a To verify that a program has been correctly 

Program saved, use the following command in C1 28 

mode: 

DVERIFY"PROGRAM NAME" III (llliri 

If the program in the computer is identical to the 
one on the disk, the screen display will respond 
with the letters "OK." 

The VERIFY command also works for tape pro- 
grams. You type: 

VERIFY"PROGRAM NAME" nf T ^fRN 

You do not enter the comma and a device 
number. 



Displaying Your In C1 28 mode, you can see a list or directory of 
Disic Directory the programs on your disk by using the following 
command: 

DIRECTORY 



This lists the contents of the directory The easy 
way is to press the F3 function key When you 
press F3, the CI 28 displays the word "DIREC- 
TORY" and performs the command. 
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For further information on SAVEing and LOAD- 
ing your progranns, or other disk related informa- 
tion, refer to your Datassette or disk drive man- 
ual. Also consult the LOAD and SAVE command 
descriptions in the Chapter V, BASIC 7.0 
Encyclopedia. 



*•••••***•••*••******•••*••••*••**•••••••*••**••*•*•** 



You now know something about the BASIC language and some ele- 
mentary programming concepts. The next section builds on these 
concepts, introducing additional commands, functions and tech- 
niques that you can use to program in BASIC. 
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Computer 
Decisions— 
The IF-THEN 
Statement 



This section describes how to use a number of powerful BASIC com- 
mands, functions and programming techniques that can be used in 
both C1 28 and C64 modes. 

These commands and functions allow you to program repeated 
actions through looping and nesting techniques; handle tables of 
values; branch or jump to another section of a program, and return 
from that section; assign varying values to a quantity — and more. 
Examples and sample programs show just how these BASIC con- 
cepts work and interact. 



Now that you know how to change the values of variables, the next 
step is to have the computer make decisions based on these 
updated values. You do this with the IF-THEN statement. You tell the 
computer to execute a command only IF a condition is true (e.g., IF 
X = 5). The command you want the computer to execute when the 
condition is true comes after the word THEN in the statement. Clear 
your computer's memory by typing NEW and pressing RETURN, 
then type this program: 

10 J = 

20 ? J,"COMMODORE 128" 

30 J = J + 1 

40 IF J<>5 THEN 20 

60 END 

You no longer have to press the STOP key to break out of a looping 
program. The IF-THEN statement tells the computer to keep printing 
"COMMODORE 1 28" and incrementing (increasing) J until J = 5 is 
true. When an I F condition is false, the computer jumps to the next 
line of the program, no matter what comes after the word THEN. 

Notice the END command in line 60. It is good practice to put an 
END statement as the last line of your program. It tells the computer 
where to stop executing statements. 
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Below is a list of comparison symbols that may be used in the IF j i 

statement and their meanings: ' — ' 

SYMBOL MEANING 

u 
u 

You should be aware that these comparisions work in expected 
mathematical ways with numbers. There are different ways to deter- 
m'me if one string is greater than, less than, or equal to another. You U 

can learn about these "string handling" functions by referring to 
Chapter V, BASIC 7.0 Encyclopedia. 

Section 5 describes some powerful extensions of the IF-THEN con- 
cept, consisting of BASIC 7.0 commands like BEGIN, BEND, and , , 
ELSE. U 



EQUALS 

GREATER THAN 

LESS THAN 

NOT EQUAL TO 

GREATER THAN OR EQUAL TO 

LESS THAN OR EQUAL TO 



Using the Colon j | 

U 



A very useful tool in programming is the colon (:). You can use the 
colon to separate two (or more) BASIC commands on the same line 



Statements after a colon on a line will be executed in order, from left 
to right. In one program line you can put as many statements as you 
can fit into 160 characters, including the line number. This is equiva- 
lent to four full screen lines in 40-column format, and two full lines in 
80-column format. This provides an excellent opportunity to take 
advantage of the THEN part of the IF-THEN statment. You can tell 
the computer to execute several commands when your IF condition 
is true. Clear the computer's memory type in the following program 
and RUN it. 
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10N=« 

15N = N + 1 LI 

20 IF N<5 THEN PRINT N;"LESS THAN 5":G0T0 15 

30 ? N; "GREATER THAN OR EQUAL TO 5" 

40 END 1_J 

U 
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Loops— The 

FOR-NEXT 

Command 



n 



Now change line 1 to read N = 20, and RUN the progrann again. 
Notice you can tell the computer to execute more than one state- 
ment when N is less than 5. You can put any statement(s) you want 
after the THEN command. Remember that the GOT0 1 5 will not be 
reached until N<5 is true. Any command that should be followed 
whether or not the specified condition Is met should appear on a 
separate line. 

In the first RUN of the program used in the previous example, we 
made the computer print the variable N five times by telling it to 
increase or "increment" the variable N by units of one, until the 
value of N equalled five; then we ended the program. There is a sim- 
pler way to do this in BASIC. We can use a FOR-NEXT loop, like this: 

10FORN = 1TO5 

20 ?N; "IS LESS THAN OR EQUAL TO 5" 

30 NEXT N 

40 END 

Type and RUN this program and compare the result with the result of 
the IF-THEN program — they are similar. In fact, the steps taken by 
the computer are almost identical for the two programs. The FOR- 
NEXT loop is a very powerful programming tool. You can specify the 
number of times the computer should repeat an action. Let's trace 
the computer's steps for the program above. 

First, the computer assigns a value of 1 to the variable N. The 5 in 
the FOR statement in line 10 tells the computer to execute all state- 
ments between the FOR statement and the NEXT statement, until N 
is equal to 5. In this case there is just one statement— the PRINT 
statement. 

This is how the computer interprets the inner workings of a FOR . . . 
NEXT loop — it operates in much the same way as the IF. . . THEN 
example on the previous page. First, the 01 28 assigns a value of 1 to 
the variable N. It then executes all instructions between the FOR and 
NEXT keywords. When the NEXT statement is encountered, it tells 
the computer to increment the counter variable N (in this case by 1), 
compare N to 5 and continue with another cycle through the FOR 
. . . NEXT loop if N = 5 is false. The increment defaults to 1 if no other 
increment is specified in the FOR statement. After five passes 
through the loop, and once N = 5 is true, the computer processes 
the statement which immediately follows the NEXT statement and 
resumes with the rest of the program. Since the computer does not 
compare the value of N to the start value of the loop variable until 
the NEXT statement is encountered, every loop is executed at least 
once. 
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40 FOR K = 1 TO 1500 
50 NEXT K 
60 PRINT A$ 
70 NEXT J 
80 END 
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Empty Loops— Inserting Delays in a Program 

Before you proceed any further, it will be helpful to understand about 

loops and sonne ways they are used to get the connputer to do what 

you want. You can use a loop to slow down the connputer (by now j j 

you have witnessed the speed with which the connputer executes 

comnnands). See if you can predict what this program will do before 

you run it. j j 

10 A$ = "COMMODORE 0128" 

20 FOR J = 1 TO 20 ^ j 

30 PRINT ^ 



u 

Did you get what you expected? The loop contained in lines 40 and 

50 tells the connputer to count to 1 500 before executing the rennain- 

der of the progrann. This is known as a delay loop and is often useful. j 1 

Because it is inside the nnain loop of the progrann, it is called a 

nested loop. Nested loops can be very useful when you want the 

connputer to perfornn a nunnber of tasks in a given order, and repeat I | 

the entire sequence of connnnands a certain nunnber of tinnes. 

Section 5 describes an advanced way to insert delays through use { I 

of the new BASIC 7.0 connnnand, SLEEP. ^^ 

u 

Tiie STEP Command 

You can tell the computer to increment your counter by units (e.g. 10, ^ | 

0.5 or any other number). You do this by using a STEP command with 
the FOR statement. For example, if you want the computer to count 

bytensto 100, type: j | 

10 FOR X = TO 100 STEP 10 

20 ?X I ) 

30 NEXT U 

Notice that you do not need the X in the NEXT statement if you are 

only executing one loop at a time — NEXT refers to the most recent ^ | 

FOR statement. Also, note that you do not have to increase (or 

"increment") your counter — you can decrease (or "decrement") it 

as well. For example, change line 1 in the program above to read: j | 

10 FOR X = 100 TO STEP- 10 

u 
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The computer will count backward from 1 00 to 0, in units of 1 0. 

If you don't use a STEP command with a FOR statement, the com- 
puter will automatically increment the counter by units of 1 . 

The parts of the FOR-NEXT command in line 10 are: 
FOR — word used to indicate beginning of loop 

X — counter variable; any number variable can be used 
1 — starting value; may be any number, positive or nega- 
tive 
TO — connects starting value to ending value 
100 — ending value; may be any number, positive or negative 
STEP — indicates an increment other than 1 will be used 
- 10 — increment; can be any number positive or negative 



The INPUT Command 

Assigning a Clear the computer's memory by typing NEW 

Value to a and pressing RETURN, and then type and RUN 

Variable this program. 

10K = 10 
20 FOR 1 = 1 TO K 
30 ? "COMMODORE" 
40 NEXT 

In this program you can change the value of K in 
line 10 to make the computer execute the loop 
as many times as you want it to. You have to do 
this when you are typing the program, before it 
is RUN. What if you wanted to be able to tell the 
computer how many times to execute the loop 
at the time the program is RUN? 

In other words, you want to be able to change 
the value of the variable K each time you run the 
program, without having to change the program 
itself. We call this the ability to interact with the 
computer. You can have the computer ask you 
how many times you want it to execute the loop. 
To do this, use the INPUT command. For exam- 
ple, replace line 10 in the program with: 

10 INPUT K 
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Prompt 
Messages 



Now when you RUN the program, the computer 
responds with a ? to let you know it is waiting for 
you to enter what you want the value of K to be. 
Type 1 5 and press RETURN. The computer will 
execute the loop 1 5 times. 

You can also make the computer print a mes- 
sage in an INPUT statement to tell you what 
variable it's waiting for. Replace line 1 with: 

10 INPUT"PLEASE ENTER A VALUE FOR 
K";K 

Remember to enclose the message to be 
printed in quotes. This message is called a 
prompt. Also, notice that you must use a semi- 
colon between the ending quote marks of the 
prompt and the K. You may put any message 
you want in the prompt, but the INPUT state- 
ment must fit within 1 60 characters, just as any 
BASIC command must. 

The INPUT statement can also be used with 
string variables. The same rules that apply for 
numeric variables apply for strings. Don't forget 
to use the $ to identify all your string variables. 
Clear your computer's memory by typing 
NEW and pressing RETURN. Then type in this 
program. 

10 INPUT"WHAT IS YOUR NAME";N$ 
20 ? "HELLO ",N$ 

Now RUN the program. When the computer 
prompts "WHAT IS YOUR NAME?", type your 
name. Don't forget to press RETURN after you 
type your name. 

Once the value of a variable (numeric or string) 
has been inserted into a program through the 
use of INPUT, you can refer to it by its variable 
name any time in the program. Type ?N$ 
(RETURN)— your computer remembers your 
name. 
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The GET Command 

There are other BASIC commands you can use in your program to 
interact with the computer. One is the GET command which is simi- 
lar to INPUT To see how the GET command works, clear the comput- 
er's memory and type this program. 

10 GET A$ 

20 IF A$ = "" THEN GOTO 10 

30?A$ 

40 END 

When you type RUN and press RETURN, nothing seems to happen. 
The reason is that the computer is waiting for you to press a key The 
GET command, in effect, tells the computer to check the keyboard 
and find out what character or key is being pressed. The computer is 
satisfied with a null character (that is, no character). This is the rea- 
son for line 20. This line tells the computer that if it gets a null charac- 
ter, indicated by the two double quotes with no space between them, 
it should go back to line 1 and try to GET another character. This 
loop continues until you press a key The computer then assigns the 
character on that key to A$. 

The GET command is very important because you can use it, in 
effect, to program a key on your keyboard. The example below prints 
a message on the screen when Q is pressed. Type the program and 
RUN it. Then press Q and see what happens. 



10 ?"PRESS Q TO VIEW MESSAGE" 

20 GET A$ 

30 IF A$ = "" THEN GOTO 20 

40 IF A$ = "Q" THEN GOTO 60 

50 GOTO 20 

60 FOR 1 = 1 TO 25 

70 ? "NOW I CAN USE THE GET STATEMENT" 

80 NEXT 

90 END 

Notice that if you try to press any key other than the Q, the computer 
will not display the message, but will go back to line 20 to GET 
another character. 

Section 5 describes how to use the DO/LOOP and GETKEY state- 
ments, which are new and more powerful BASIC 7.0 commands that 
can be used to perform a similar task. 
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Sample Program i | 

Now that you know how to use the FOR-NEXT loop and the INPUT 
connnriand, c lear the connputer's nnennory by typing NEW 

i, then type the following program: j } 



10T = 

20 INPUT"HOW MANY NUMBERS";N 

30FORJ = 1TON 

40 INPUT"PLEASE ENTER A NUMBER ";X 

50T = T + X 

60 NEXT 

70A = T/N 

80 PRINT 

90 ? "YOU HAVE";N"NUMBERS TOTALING";T 

100? "AVERAGE =";A 

110 END [ 



Line 60 tells the computer to go back to line 30, increment the 
counter (J) and start the loop again. 

Line 70 divides the total by the amount of numbers you typed 
(N) after the loop has been executed N times. 



Line 90 prints the message that gives you the amount of num- 
bers and their total. 



Line 1 00 prints the average of the numbers. 

Line 1 1 tells the computer that your program is finished. 
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This program lets you tell the computer how many numbers you want 
to average. You can change the numbers every time you run the 
program without having to change the program itself. 

Let's see what the program does, line by line: 

Line 1 assigns a value of to T (which will be the running total 
of the numbers). 

Line 20 lets you determine how many numbers to average, j | 

stored in variable N. 

Line 30 tells the computer to execute a loop N times. 

Line 40 lets you type in the actual numbers to be average^j. 

Line 50 adds each number to the running total. 



u 
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Line 80 prints a blank line on the screen. j j 

u 
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The READ-DATA Command 

There is another powerful way to tell the computer what numbers or 
characters to use in your program. You can use the READ statement 
in your program to tell the computer to get a number or character(s) 
from the DATA statement. For example, if you want the computer to 
find the average of five numbers, you can use the READ and DATA 
statements this way: 

10T = 

20FOR J = 1T0 5 

30 READ X 

40T = T + X 

50 NEXT 

60A = T/5 

70? "AVERAGE =";A 

80 END 

90 DATA 5,12,1,34,18 

When you run the program, the computer will print AVERAGE = 14. 
The program uses the variable T to keep a running total, and calcu- 
lates the average in the same way as the INPUT average program. 
The READ-DATA average program, however, finds the numbers to 
average on a DATA line. Notice line 30, READ X. The READ com- 
mand tells the computer there must be a DATA statement in the pro- 
gram. It finds the DATA line, and uses the first number as the current 
value for the variable X. The next time through the loop the second 
number in the DATA statement will be used as the value for X, and 
soon. 

You can put any number you want in a DATA statement, but you can- 
not put calculations in a DATA statement. The DATA statement can 
be anywhere you want in the program — even after the END state- 
ment. This is because the computer never really executes the DATA 
statement; it just refers to it. Be sure to separate your data items 
with commas, but be sure not to put a comma between the word 
DATA and the first number in the list. 

If you have more than one DATA statement in your program, the com- 
puter will refer to the one that is closest after the READ statement 
being executed at the time. The computer uses a pointer to remind 
itself which piece of data it read last. After the computer reads the 
first number in the DATA statement, the pointer points to the second 
number. When the computer comes to the READ statement again, it 
assigns the second number to the variable name in the READ 
statement. 
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You can use as many READ and DATA statements as you need in a 
program, but make sure there is enough data in the DATA statements 
for the computer to read. Remove one of the numbers from the DATA 
statement in the last program and run it again. The computer 
responds with ?OUT OF DATA ERROR IN 30. What happened is that 
when the computer executed the loop for the fifth time, there was no 
data for it to read. That is what the error message is telling you. Put- 
ting too much into the DATA statement doesn't create a problem 
because the computer never realizes the extra data exists. 



u 
u 
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The RESTORE Command 

You can use the RESTORE command in a program to reset the data [I 

pointer to the first piece of data if you need to. Replace the END 
statement (line 80) in the program above with: 

80 RESTORE U 

and add: 

85 GOTO 10 U 

Now RUN the program. The program will run continuously using the 
same DATA statement. NOTE: If the computer gives you an OUT OF I | 

DATA ERROR message, it is because you forgot to replace the num- 
ber that you removed previously from the DATA statement, so the 
data is all used before the READ statement has been executed the 
specified number of times. 



10FOR J = 1T0 3 

20 READ A$ 

30?A$ 

40 NEXT 

50 END 

60 DATA COMMODORE,128,COMPUTER 

If the READ statement calls for a string variable, you can place let- 
ters or numbers in the DATA statement. Notice however, that since 
the computer is READing a string, numbers will be stored as a string 
of characters, not as a value which can be manipulated. Numbers 
stored as strings can be printed, but not used in calculations. Also, 
you cannot place letters in a DATA statement if the READ statement 
calls for a number variable. 
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You can use DATA statements to assign values to string variables. j j 

The same rules apply as for numeric data. Clear the computer's 
memory and type the following program: 

Lj' 
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Using Arrays 

You have seen how to use READ-DATA to provide many values for a 
variable. But what if you want the connputer to remember all the data 
in the DATA statement instead of replacing the value of a variable 
with the new data? What if you want to be able to recall the third 
number, or the second string of characters? 

Each time you assign a new value to a variable, the computer erases 
the old value in the variable's box in memory and stores the new 
value in its place. You can tell the computer to reserve a row of 
boxes in memory and store every value that you assign to that varia- 
ble in your program. This row of boxes is called an array 



Subscripted 
Variables 



If the array contains all of the values assigned to 
the variable X in the READ-DATA example, it is 
called the X array The first value assigned to X 
in the program is named X(1), the second value 
is X(2), and so on. These are called subscripted 
variables. The numbers in the parentheses are 
called subscripts. You can use a variable or a 
calculation as a subscript. The following is 
another version of the averaging program, 
this time using subscripted variables. 

5 DIM X(5) 
101 = 
15: 

20FORJ=:1TO5 
30 READ X(J) 
40T = T + X(J) 
50 NEXT 
55: 

60A = T/5 

70? "AVERAGE =";A 
80 END 
85: 
90 DATA 5,12,1,34,18 

Notice there are not many changes. Line 5 is the 
only new statement. It tells the computer to set 
aside five storage compartments (25 bytes) in 
memory for the X array Line 30 has been 
changed so that each time the computer exe- 
cutes the loop, it assigns a value from the DATA 
statement to the position in the X array that cor- 
responds to the loop counter (J). Line 40 calcu- 
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10 DIM X(10,5) 
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lates the total, just as it did before, but you must 
use a subscripted variable to do it. 

After you run the program, if you want to recall 
the third number, type ?X(3)<RETURN>. The [J 
computer remembers every number in the array 
X. You can create string arrays to store the char- 
acters in string variables the same way Try ) I 
updating the COMMODORE 128 COMPUTER 
READ-DATA program so the computer will 
remember the elements in the A$ array. j j 

5 DIM A$(3) 

10FOR J = 1T0 3 

20 READ A$(J) 

30 ? A$(J) 

40 NEXT 

50 END 

60 DATA COMMODORE,C128,COMPUTER 

TIP: You do not need the DIM statement in your I] 

program unless the array you use has more than 

10 elements. See DIMENSIONING ARRAYS. 

j 1 

Dimensioning Arrays can be used with nested loops, so the 
Arrays computer can handle data in a more advanced 

way What if you had a large chart with 1 rows j { 

and 5 numbers in each row. Suppose you 

wanted to find the average of the five numbers 

in each row. You could create 1 arrays and [ | 

have the computer calculate the average of the 

five numbers in each one. This is not necessary 

because you can put all the numbers in a two- | j 

dimensional array This array would have the 

same dimensions as the chart of numbers you 

want to work with — 10 rows by 5 columns. The j j 

DIM statement for this array (we will call it array 

X) should be: 
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This tells the computer to reserve space in its 

memory for a two-dimensional array named X. ^ I 

The computer reserves enough space for 50 

numbers. You do not have to fill an array with as 

many numbers as you DIMensioned it for, but j I 

the computer will still reserve enough space for ^ ' 

all of the positions in the array 



u 



n 
n 
n 
n 

r— 1 
i I 



n 
n 
n 
n 
n 
n 

n 
n 
n 



1 1 
n 



Sample 
Program 



Now it becomes very easy to refer to any num- 
ber in the chart by its column and row position. 
Refer to the chart below. Find the third element 
in the tenth row (1 500). You would refer to this 
number as X(1 0,3) in your program. The pro- 
gram at the bottom of this page reads the num- 
bers from the chart into a two-dimensional array 
(X) and calculates the average of the numbers in 
each row. 









Columr 


1 




Row 


1 


2 


3 


4 


5 


1 


1 


3 


5 


7 


9 


2 


2 


4 


6 


8 


10 


3 


5 


10 


15 


20 


25 


4 


10 


20 


30 


40 


50 


5 


20 


40 


60 


80 


100 


6 


30 


60 


90 


120 


150 


7 


40 


80 


120 


160 


200 


8 


50 


100 


150 


200 


250 


9 


100 


200 


300 


400 


500 


10 


500 


1000 


1500 


2000 


2500 
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Programming 
Subroutines 



The GOSUB-RETURN Command 

Until now, the only method you have had to tell the computer to jump 
to another part of your program is to use the GOTO command. What 
if you want the computer to jump to another part of the program, 
execute the statements in that section, then return to the point it left 
off and continue executing the program? 

The part of program that the computer jumps to and executes is 
called a subroutine. Clear your computer's memory and enter the 
program below. 

10 A$ = "SUBROUTINE":B$ = "PROGRAM" 

20FOR J = 1T0 5 

30 INPUT "ENTER A NUMBER";X 

40 GOSUB 100 

50 PRINT B$:PRINT 

60 NEXT 

70 END 

100 PRINT A$:PRINT 

110Z = Xt2:PRINTZ 

120 RETURN 

This program will square the numbers you type and print the result. 
The other print messages tell you when the computer is executing 
the subroutine or the main program. Line 40 tells the computer to 
jump to line 1 00, execute it and the statements following it until it 
sees a RETURN command. The RETURN statement tells the com- 
puter to go back in the program to the statement following the 
GOSUB command and continue executing. The subroutine can be 
anywhere in the program — including after the END statement. Also, 
remember that the GOSUB and RETURN commands must always 
be used together in a program (like FOR-NEXT and IF-THEN), other- 
wise the computer will give an error message. 
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Using Memory 
Locations 
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The ON GOTO/GOSUB Command 

There is another way to make the computer jump to another section 
of your program (called branching). Using the ON statement, you can 
have the computer decide what part of the program to branch to 
based on a calculation or keyboard input. The ON statement is used 
with either the GOTO or GOSUB-RETURN commands, depending on 
what you need the program to do. A variable or calculation should be 
after the ON command. After the GOTO or GOSUB command, there 
should be a list of line numbers. Type the program below to see how 
the ON command works. 

10 ? "ENTER A NUMBER BETWEEN ONE AND FIVE" 

20 INPUT X 

30 ON X GOSUB 100,200,300,400,500 

40 END 

100 ? "YOUR NUMBER WAS ONE":RETURN 

200 ? "YOUR NUMBER WAS TWO":RETURN 

300 ? "YOUR NUMBER WAS THREE":RETURN 

400 ? "YOUR NUMBER WAS FOUR":RETURN 

500 ? "YOUR NUMBER WAS FIVE":RETURN 

When the value of X is 1 , the computer branches to the first line num- 
ber in the list (1 00). When X is 2, the computer branches to the sec- 
ond number in the list (200), and so on. 



Using PEEK and POKE for RAM/ROM Access 

Each area of the computer's memory has a special function. For 
instance, there is a very large area to store your programs and the 
variables associated with them. This part of memory called RAM, is 
cleared when you use the NEW command. Other areas are not as 
large, but they have very specialized functions. For instance, there is 
an area of memory locations that controls the music features of the 
computer. 

There are two BASIC commands — PEEK and POKE — that you can 
use to access and manipulate the computer's memory Use of PEEK 
and POKE commands can be a powerful programming device 
because the contents of the computer's memory locations deter- 
mine exactly what the computer should be doing at a specific time. 
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Using PEEK PEEK can be used to make the computer tell 

you what value is being stored in a memory 
location (a memory location can store any value 
between and 255). You can PEEK the value of 
any memory location (RAM or ROM) in DIRECT 
or PROGRAM mode. Type: 

P^PEEKg594) HI iiini J 

The computer assigns the value in memory 
location 2594 to the variable P when you press 
RETURN after the first line. Then it prints the 
value when you press RETURN after entering 
the ? P command. Memory location 2594 deter- 
mines whether or not keys like the spacebar and 
CRSR repeat when you hold them down. A 128 
in location 2594 tells the computer to repeat 
these keys when you hold them down. Hold 
down the spacebar and watch the cursor move 
across the screen. 
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Using POKE To change the value stored in a RAM location, 

use the POKE command. Type: 

POKE 2594,96 HhlUHM 

The computer stores the value after the comma 
(96) in the memory location before the comma 
(2594). A 96 in memory location 2594 tells the 
computer not to repeat keys like the spacebar 
and CRSR keys when you hold them down. Now 
hold down the spacebar and watch the cursor. 
The cursor moves one position to the right, but it 
does not repeat. To return your computer to its 
normal state, type: 

POKE 2594,128 HI MfHH 

You cannot alter the value of all the memory 
locations in the computer — the values in ROM 
can be read, but not changed. 

NOTE: These examples assume you are in 
bank J2f. See the description of the BANK 
command in Chapter V, BASIC 7.0 Encyclo- 
pedia for details on banks. Refer to the 
Commodore 128 Programmer's Reference 
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Basic Functions 



Guide for a complete memory map of the 
computer, which shows you the contents of 
all memory locations. 



Wliat Is a Function? 



A function is a predefined operation of the BASIC language that gen- 
erally provides you with a single value. When the function provides 
the value, it is said to "return" the value. For instance, the SQR 
(square root) function is a mathematical function that returns the 
root value of a specific number before it is raised to the second 
power — i.e., the value returned when multiplied by itself (squared) is 
equal to the argument used in the function. 

There are two kinds of functions: 

Numeric — returns a result which is a single number. Numeric 
functions range from calculating mathematical values to speci- 
fying the numeric value of a memory location. 

String — returns a result which is a character. 

Following are descriptions of some of the more commonly used 
functions. For a complete list of BASIC 7.0 functions see Chapter V, 
BASIC 7.0 Encyclopedia. 

The INTEGER Function (INT) 

What if you want to round off a number to the nearest integer? You'll 
need to use INT, the integer function. The INT function takes away 
everything after the decimal point (for positive numbers only). Try 
typing these examples: 

? INT(4.25) 
? INT(4.75) 
? INT(SQR(50)) 

If you want to round off to the nearest whole number, then the sec- 
ond example should return a value of 5. In fact, you should round up 
any number with a decimal of 0.5 and above. To do this, you have to 
add 0.5 to the number before using the INT function. In this way 
numbers with decimal portions of 0.5 and above will be increased by 
1 before being rounded down by the INT function. Try this: 

?INT(4.75 + 0-5); 
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The computer added 0.5 to 4.75 before it executed the INT function, 
so that it rounded 5.25 down to 5 for the result. If you want to round 
off the result of a calculation, do this: 

? INT{(100/6) + 0.5) III lllliri 

You can substitute any calculation for the division shown in the inner 
parentheses. 

What if you want to round off nunnbers to the nearest 0.01? Instead of 
adding 0.5 to your nunnber, add 0.005, then multiply by 1 00. Let's say 
you want to round 2.876 to the nearest 0.01 . Using this method, you 
start with: 

? (2.876 + 0.005)*100 HLIUHN 

Now use the I NT function to get rid of everything after the decimal 
point (which moves two places to the right when you multiply by 
100). You are left with: 



?INT((2.876 + 0.005)*100): 

which gives you a value of 288. All that's left to do is divide by 1 00 to 
get the value of 2.88, which is the answer you want. Using this tech- 
nique, you can round off calculations like the following to the nearest 
0.01: 
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? INT({2.876 + 1.29 + 16.1-9.534) + 0.005)*100/100 \ 



Generating Random Numbers— The RND Function 

The RND functions tells the computer to generate a random number. 
This can be useful in simulating games of chance, and in creating 
interesting graphic or music programs. All random (RND) numbers 
are nine digits, in decimal form, between the values 0.000000001 
and 0.999999999. Typ- 

Multiplying the randomly generated number by six makes the range 
of generated numbers increase to greater than and less than 6. In 
order to include 6 among the numbers generated, we add one to the 
result of RND(0)*6. This makes the range 1 <X<7. If we use the INT 
function to eliminate the decimal places, the command will generate 
whole numbers from 1 to 6. This process can be used to simulate the 
rolling of a die. Try this program: 

10 R= INT(RND(1)*6 + 1) 

20 ?R 

30 GOTO 10 
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Each number generated represents one toss of a die. To simulate a 
pair of dice, use two commands of this nature. Each number is gen- 
erated separately, and the sum of the two numbers represents the 
total of the dice. 
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The ASC and CHR$ Functions 

Every character that the Commodore 1 28 can display (including 
graphic characters) has a number assigned to it. This number is 
called a character string code (CHR$) and there are 256 of them in 
the Commodore 128. There are two functions associated with this 
concept that are very useful. The first is the ASC function. Type: 



?ASC("Q") i 

The computer responds with 81 . 81 is the character string code for 
the Q key Substitute any character for Q in the command above to 
find out the Commodore ASCII code number for any character. 

The second function is the CHR$ function. Type: 

The computer responds with Q. In effect, the CHR$ function is the 
opposite of the ASC function. They both refer to the table of charac- 
ter string codes in the computer's memory CHR$ values can be 
used to program function keys. See Section 5 for more information 
about this use of CHR$. See Appendix E of this Guide for a full listing 
of ASC and CHR$ codes. 



Converting Strings and Numbers 

Sometimes you may need to perform calculations on numeric char- 
acters that are stored as string variables in your program. Other 
times, you may want to perform string operations on numbers. There 
are two BASIC functions you can use to convert your variables from 
numeric to string type and vice versa. 
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The STOP and 
CONT (Continue) 
Commands 



The VAL The VAL function returns a nunneric value for a 

Function string argument. Clear the connputer's nnennory 

and type this program: 

10A$ = "64" 

20A = VAL(A$) 

30 ? "THE VALUE OF";A$;"IS";A 

40 END 

The STR$ The STR$ function returns the string representa- 

Function tion of a numeric value. Clear the computer's 

memory and type this program. 

10A = 65 

20A$ = STR$(A) 

30 ? A" IS THE VALUE OF";A$ 



The Square Root Function (SQR) 

The square root function is SQR. For example, to find the square root 
of 50, type: 

You can find the square root of any positive number in this way 

The Absoiute Vaiue Function (ABS) 

The absolute value function (ABS) is very useful in dealing with nega- 
tive numbers. You can use this function to get the positive value of 
any number — positive or negative. Try these examples: 

? ABS(5)" IS EQUAL TO "ABS(- 5) \ 



You can make the computer stop a program, and resume running it 
when you are ready The-STOP command must be included in the 
program. You can put a STOP statement anywhere you want to in a 
program. When the computer "breaks" from the program (that is, 
stops running the program), you can use DIRECT mode commands 
to find out exactly what is going on in the program. For example, you 
can find the value of a loop counter or other variable. This is a power- 
ful device when you are "debugging" or fixing your program. Clear 
the computer's memory and type the program below. 
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10X = INT(SQR(630)) 

20Y = (.025*80)t2 

30Z=INT(X*Y) 

40 STOP 

45 ? "RESUME PROGRAMMING" 

50A = (X* Y) + Z 

80 END 

Now RUN the program. The computer responds with "BREAK IN 
40". At this point, the computer has calculated the values of X, Y and 
Z. If you want to be able to figure out what the rest of the program is 
supposed to do, tell the computer to PRINT X;Y;Z. Often when you 
are debugging a large program (or a complex small one), you'll want 
to know the value of a variable at a certain point in the program. 

Once you have all the information you need, you can type CONT (for 
CONTinue) and press RETURN assuming you have not edited any- 
thing on the screen. The computer then CONTinues with the pro- 
gram, starting with the statement after the STOP command. 
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This section and the preceding one have been designed to famiiiar- 
ize you with the BASIC programming language and some of its capa- 
biiities. The remaining four sections of this chapter describe com- 
mands that are unique to Commodore 128 mode. Many Commodore 
128 mode commands provide capabiiities that are not available in 
C64 mode. Other Commodore 128 mode commands let you do the 
same thing as certain C64 commands, but more easily Remember 
that more information on every command and programming tech- 
nique in this book can be found in the Commodore 128 Program- 
mer's Reference Guide. The syntax for all Commodore 7.0 com- 
mands is given in Chapter V, BASIC 7.0 Encyclopedia. 
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Advanced 
Looping 



This section introduces you to sonne powerful BASIC connnnands and 
statements that you probably haven't seen before, even if you are an 
experienced BASIC progrannmer. If you're fanniliar with programnning 
in BASIC, you've probably encountered nnany situations in which you 
could have used these commands and statements. This section 
explains the concepts behind each command and gives examples of 
how to use each command in a program. (A complete list and an 
explanation of these commands and statements may be found in 
Chapter V, BASIC 7.0 Encyclopedia.) This section also describes how 
to use the special keys that are available to you in CI 28 mode. 



Tlie DOf LOOP Statement 

The DO/LOOP statement provides more sophisticated ways to cre- 
ate a loop than do the GOTO, GOSUB or FOR/NEXT statements. The 
DO/LOOP statement combination brings to the BASIC language a 
very powerful and versatile technique normally available only in 
structured programming languages. We'll discuss just a few possible 
uses of DO/LOOP in this explanation. 

If you want to create an infinite loop, you start with a DO statement, 
then enter the line or lines that specify the action you want the com- 
puter to perform. Then end with a LOOP statement, like this: 

100 DO 

110 PRINT "REPETITION" 

120 LOOP 

Press the RUN/STOP key to stop the program. 

The directions following the DO statement are carried out until the 
program reaches the LOOP statement (line 120); control is then 
transferred back to the DO statement (line 100). Thus, whatever 
statements are in between DO and LOOP are performed indefinitely 



Until Another useful technique is to combine the DO/ 

LOOP with the UNTIL statement. The UNTIL 
statement sets up a condition that directs the 
loop. The loop will run continually unless the 
condition for UNTIL happens. 

100 DO: 

110 : INPUT "DO YOU LIKE YOUR COMPUTER";A$ 

120 LOOP UNTIL A$ = "YES" 

130 PRINT "THANK YOU" 
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The DO/LOOP statement is often used to repeat 
an entire routine indefinitely in the body of a 
progrann, as in the following: 



u 



io 


PRINT"THE PROGRAM RUNS UNTIL YOU TYPE 'QUIT'" 




.20 


DO 




30 


: INPUT"DEGREES FAHRENHEIT" ;F 




40 


: C=(5/9)*(F-32) 




55 


: JPRINT F; "DEGREES FAHRENHEIT"; 




; 5 6 


: PRINT"EQUALS ";C;" DEGREES CELSIUS" 




60 


: INPUT "AGAIN OR QUIT";A$ 




70 


LOOP UNTIL A$="QUIT" 




80 


END 





Another use of DO/LOOP is as a counter, where 
the UNTIL statennent is used to specify a certain 
nunnber of repetitions. 



10 N=2*2 




20 PRINT "TWO DOUBLED EQUALS" ;N 




30 DO 




40 : X==X+1 




50 : N=N*2 




60 : . PRINT "DOUBLED" ;X+1 ; "TIMES . . 


.";N 


p; fcOOP UNTIL X=25 




80 ilND 





Notice that if you leave the counter statement 
out (the UNTIL X = 25 part in line 70), the num- 
ber is doubled indefinitely until an OVERFLOW 
error occurs. 
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While 



The WHILE statement works in a similar way to 
UNTIL, but the loop is repeated only while the 
condition is in effect, such as in this reworking 
of this brief program: 



M 

20 

. 3.0 

50 


BO 

• 

LOOP ' 
PRINT 
END 


INPUT "DO YOU LIKE 
WHILE A$<>"YES" 
"THANK YOU" 


YOUR 


COMPUTER" 


;A$ 



Exit 



An EXIT statement can be placed within the 
body of a DO/LOOR When the EXIT statement is 
encountered, the program jumps to the next 
statement following the LOOP statement. 
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The ELSE Clause with IF-THEN 

The ELSE clause provides a way to tell the computer how to respond 
if the condition of the IF-THEN statement is false. Rather than contin- 
uing to the next program line, the computer will execute the com- 
mand or branch to the program line mentioned in the ELSE clause. 
For example, if you wanted the computer to print the square of a 
number, you could use the ELSE clause like this: 



10 DO 




20 




INPUT "ENTER A NUMBER TO BE SQUARED" ;N 


30 ' 




IF N < 100 THEN PRINT N*N:ELSE 60 


40 




PRINT"PRESS 'Q' TO QUIT" ; 


50 ' 




INPUT A$ 


60 ^ 




PRINT:'':NUMBER' MUST -BE < 1,00" 


70 LOOP 


UNTIL A$="Q" ^ 1 


80 END 





Notice that you must use a colon between the IF-THEN statement 
and the ELSE clause. 
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The BEGIN/BEND Sequence with IF-THEN 

BASIC 7.0 allows you to take the IF-THEN condition one step further. 
The BEGIN/BEND sequence permits you to include a number of pro- 
gram lines to be executed if the IF condition is true, rather than one 
simple action or GOTO. The command is constructed like this: 

IF condition THEN BEGiN: 
(program iines): 
BEND:ELSE 

Be sure to place a colon between BEGIN and any instructions to be 
executed and again between the last command in the sequence and 
the word BEND. BEGIN/BEND can be used without an ELSE clause, 
or can be used following the ELSE clause when only a single com- 
mand follows THEN. Try this program: 



10 DO 


20 


INPUT "ENTER A NUMBER" ; A 


30 


IF A < 100 THEN BEGIN 


40 


PRINT"Y0UR NUMBER WAS ";A 


50 


SLEEP 2: REM DELAY 


60 


FOR X=l TO A 


70 


PRINT"THIS IS A BEGIN/BEND EXAMPLE" 


80 


NEXT X 


90 


PRINT "THAT'S ENOUGH" 


100 : BEND :ELSE PRINT" TOO MANY" 


110: INPUT" DO YOU WANTT TO QUIT ( Y/N ) " ? A$ ; ;/: 


120 LOOP UNTIL A$="Y" 


130 END 
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This program asks for a number from the user. IF the number is less 
than 100, the statements between the keywords BEGIN and BEND 
are performed, along with any statements on the same line as BEND 
(except for ELSE). The message "YOUR NUMBER WAS N" appears 
on the screen. Line 50 is a delay loop used to keep the message on 
the screen long enough so it can be read easily Then a FOR/NEXT 
loop is used to display a message for the number of times specified 
by the user. If the number is greater than 1 00, the THEN condition is 
skipped, and the ELSE condition (printing "TOO MANY") is carried 
out. The ELSE keyword must be on the same line as BEND. 
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Formatting 
Output 



The SLEEP Command 

Note the use of the SLEEP command in line 50 of the program just 
discussed. SLEEP provides an easier, more accurate way of insert- 
ing and timing a delay in program operation. The format for the 
SLEEP command is 

SLEEP n 

where n indicates the number of seconds, in the range 1 to 65535, 
that you want the program to delay In the command shown in line 
50, the 2 specifies a delay of two seconds. 



The PRINT USING Command 

Suppose you were writing a sales program that calculated a dollar 
amount. Total sales divided by number of salespeople equals aver- 
age sales. But performing this calculation might result in dollar 
amounts with four or five decimal places! You can format the results 
the computer prints so that only two decimal places are displayed. 
The command which performs this function is PRINT USING. 

PRINT USING lets you create a format for your output, using spaces, 
commas, decimal points and dollar signs. Hash marks (the # sign) 
are used to represent spaces or characters in the displayed result. 
For example: 

PRINT USING "#$#####.##";A 

tells the computer that when A is printed, it should be in the form 
given, with up to five places to the left of the decimal point, and two 
places to the right. The hash mark in front of the dollar sign indicates 
that the $ should float; that is, it should always be placed next to the 
left-most number in the format. 
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Sample Program 
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If you want a comma to appear before the last three dollar places, as 
in $1 ,000.00. include the comma in the PRINT USING statement. 
Remember you can format output with spaces, commas, decimal 
points, and dollar signs. There are several other special characters 
for PRINT USING, see the BASIC Encyclopedia for more information. 

The PUDEF Command 

If you want formatted output representing something other than dol- 
lars and cents, use the PUDEF (Print Using DEFine) command. You 
can replace any of four format characters with any character on the 
keyboard. 

The PUDEF command has four positions, but you do not have to 
redefine all four. The command looks like this: 



PUDEF". 



1 



_> ■ $ 

2 3 4 



Here: 



• position 1 is the filler character. A blank will appear if you do 
not redefine this position. 

• position 2 is the comma character. Default is the comma. 

• position 3 is the decimal point. 

• position 4 is the dollar sign. 

If you wrote a program that converted dollar amounts to English 
pounds, you could format the output with these commands: 

10 PUDEF " £" 

20 PRINT USING "#$####.##";X 



This program calculates interest and loan payments, using some of 
the commands and statements you just learned. It sets a minimum 
value for the loan using the ELSE clause with an IF-THEN statement, 
and sets up a dollar and cents format with PRINT USING. 



10 INPUT "LOAN AMOUNT IN DOLLARS"; A 

20 IF A<100 THEN 70: ELSE P=.15 

30 I=A*P 

40 PRINT"TOTAL PAYMENT EQUALS"; 

50 PRINT USING "#$#####.##" ;A+I 

60 GO TO 80 

70 PRINT"LOANS OF UNDER $100 NOT AVAILABLE" 

80 END 
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with the GETKEY 
Command 
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You have learned to use INPUT and GET comnnands to enter DATA 
during a progrann. Another way for you to enter data while a program 
is being RUN is with the GETKEY statennent. The GETKEY statement 
accepts only one key at a time. GETKEY is usually followed by a 
string variable (A$, for example). Any key that is pressed is assigned 
to that string variable. GETKEY is useful because it allows you to 
enter data one character at a time without having to press the 
RETURN key after each character. The GETKEY statement may only 
be used in a program. 

Here is an example of using GETKEY in a program: 

1000 PRINT "PLEASE CHOOSE A, B, 0, D, E, OR F" 

1010 GETKEY A$ 

1020 PRINT A$;" WAS THE KEY YOU PRESSED." 

The computer waits until a single key is pressed; when the key is 
pressed, the character is assigned to variable A$, and printed out in 
line 1020. The following program features GETKEY in more complex 
and useful fashions: for answering a multiple-choice question and 
also asking if the question should be repeated. If the answer given is 
incorrect, the user has the option to try again by pressing the "Y" 
key (line 90). The key pressed for the multiple choice answer is 
assigned to variable A$ while the 'TRY AGAIN" answer is assigned 
to B$, through the GETKEY statements in lines 60 and 90. IF/THEN 
statements are used for loops in the program to get the proper com- 
puter reaction to the different keyboard inputs. 

10 PRINT "WHO WROTE THE RAVEN'?" 

20 PRINT "A. EDGAR ELLEN POE" 

30 PRINT "B. EDGAR ALLAN POE" 

40 PRINT "C. IGOR ALLEN POE" 

50 PRINT "D. ROB RAVEN" 

60 GETKEY A$ 

70IFA$ = "B"THEN150 

80 PRINT "WRONG. TRY AGAIN? (Y OR N)" 

90 GETKEY B$ 

100 IF B$ = "Y" THEN PRINT "A,B,C, OR D?":GOTO 60 

110IFB$ = "N"THEN140 

120 PRINT "TYPE EITHER Y OR N— TRY AGAIN" 

130 GOTO 90 

140 PRINT "THE CORRECT ANSWER IS B." 

145 GOTO 160 

150 PRINT "CORRECT!" 

160 END 
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Aids 
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GETKEY is very similar to GET, except GETKEY will automatically 
wait for a key to be pressed. 



In earlier sections, you learned how to make changes in your pro- 
grams, and correct typing mistakes with INST/DEL. BASIC also pro- 
vides other commands and functions which help you locate actual 
progam errors, and commands which you can use to make program- 
ming sessions flow more smoothly. 



Entering Programs 



Auto 



Renumber 



C128 BASIC provides an auto-numbering pro- 
cess. You determine the increment for the line 
numbers. Let's say you want to number your 
program in the usual manner, by tens. Before 
you begin to program, while in DIRECT mode, 
type: 

The computer will automatically number your 
program by tens. When you press the RETURN 
key, the next line number appears, and the cur- 
sor is in the correct place for you to type the 
next statement. You can choose to have the 
computer number the commands with any 
increment; you might choose 5 or even 50. Just 
place the number after the word AUTO and 
press RETURN. To turn off the auto-numbering 
feature, type AUTO with no increment, and 
press RETURN. 

If you write a program and later add statements 
to it, sometimes the line numbering can be awk- 
ward. Using the RENUMBER command you can 
change the line numbers to an even increment 
for part or all of your program. The RENUMBER 
command has several optional parameters, as 
listed below in brackets: 

RENUMBER [new starting line[, 

increment[,old starting line]]] 
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The new starting line is what the first progrann 
line will be numbered after the RENUMBER 
command is used. If you don't specify, the 
default is 1 0. The increment is the spacing 
between line numbers, and it also defaults to 10. 
The old starting line number is the line number 
where renumbering is to begin. This feature 
allows you to renumber a portion of your pro- 
gram, rather than all of it. It defaults to the first 
line of the program. For example, 

RENUMBER 40„80 

tells the computer to renumber the program 
starting at line 80, in increments of 10. Line 80 
becomes line 40. 

Notice that this command, like AUTO, can only 
be executed in DIRECT mode. 



DELETE 10-50 



DELETE-120 

erases all lines up to and including 120 
DELETE 120- 

erases line 120 and any line after it 
DELETE 120 

erases line 120 only 
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Delete You know to delete program lines by typing the 

line number and pressing the RETURN key This 

can be tedious if you want to erase an entire j | 

portion of your program. The DELETE command 
can save you time because you can specify a 

range of program lines to erase all at once. For 1 | 

example, 



u 



will erase lines 10, 50, and any in between. The 
use of DELETE is similar to that of LIST, in that 

you can specify a range of lines up to a given 1 j 

line, or following it, or a single line only as in 
these examples: 
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Identifying Problems in Your Programs 

When a program doesn't work the way you expected, an error mes- 
sage usually occurs. Sometimes the messages are vague, however, 
and you still don't understand the problem. The Commodore 128 
computer has several ways of helping you locate the problem. 



Help 



Error 

IVapping— The 
TRAP Command 



The Commodore 1 28 provides a HELP com- 
mand that specifies the line in which a problem 
has occurred. To actuate the HELP command, 
just press the special HELP key on the row of 
keys located above the main keyboard. 

Type the following statement. It contains an 
intentional error, so type it just as is: 

10 ?3;4:5;6 

When you RUN this one-line program, the com- 
puter prints 3 and 4 as expected, but then 
responds "SYNTAX ERROR IN 10". Let's sup- 
pose you can't see the error (a colon instead of 
a semicolon between 4 and 5). You press the 
HELP key (You can also type HELP and press 
RETURN.) The computer displays the line again, 
but the 5;6 is highlighted to show the error is in 
that line. 



Usually if an error occurs in a program, the pro- 
gram "crashes" (stops running). At that point, 
you can press the HELP key to track down the 
error. However, you can use the BASIC 7.0 
TRAP command to include an error-trapping 
capability within your program. The TRAP com- 
mand advises you to locate and correct an error, 
then resumes program operation. Usually the 
error-trapping function is set in the first line of a 
program: 

5 TRAP 100 

tells the computer that if an error occurs to go to 
a certain line (in this case, line 1 00). Line 1 00 
appears at the end of the program, and sets up 
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a contingency. Neither line is executed UNLESS 
tliere is an error. Wlien an error occurs, the line 
with the TRAP statement is enacted, and control 
is directed to another part of the progrann. You 
can use these statements to catch anticipated 
errors in entering data, resume execution, or 
return to text mode from a graphics mode, to 
name just a few options. If you run the DO/LOOP 
example (which doubled numbers) without an 
UNTIL statement, you can get an OVERFLOW 
error and the program crashes. You can prevent 
that from happening by adding two lines, one at 
the beginning of the program and one at the 
end. For this example, you might add these two 
lines: 

5 TRAP 100 

100 IF N>1 THEN END 

Even though N has been much greater than one 
for the entire program, the statement isn't con- 
sidered until there is an error. When the number 
"overflows" (is greater than the computer can 
accept), the TRAP statement goes into effect. 
Since N is greater than one, the program is 
directed to END (rather than crashing.) 

Here is an example in which trapping is used to 
prevent a zero from being input for division: 
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Notice the RESUME in line 1 1 00. This tells the 
computer to return to the line mentioned (in this 
case, 120) and continue. Depending on the error 
that was trapped, resuming execution may or 
may not be possible. 

For additional information on error trapping, see 
the error functions ERRS, EL and ER, described 
in Chapter V, BASIC 7.0 Encyclopedia. 
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Program 
Tracing— The 
TRON and 
TROFF 
Commands 



When a problem in a program occurs, or you do 
not get the results you expect, it can be useful to 
methodically work through the program and do 
exactly what the computer would do. This pro- 
cess is called tracing. Draw variable boxes and 
update the values according to the program 
statements. Perform calculations and print 
results following each instruction. 

Tracing may show you, for example, that you 
have used a GOTO with an incorrect line num- 
ber, or calculated a result but never stored it in a 
variable. Many program errors can be located 
by pretending to be the computer, and following 
only one instruction at a time. Your CI 28 can 
perform a type of trace using the special com- 
mands TRON and TROFF (short for TRace ON 
and TRace OFF). When the program is run, with 
TRACE ON the computer prints the line num- 
bers in the order they are executed, as well as 
any results. In this way you may be able to see 
why your program is not giving the results you 
expected. 

Type any short program we have used so far, or 
use one of your own design. To activate trace 
mode, type TRON in DIRECT mode. When you 
run the program, notice how line numbers 
appear in brackets before any results are dis- 
played. Try to follow the line numbers and see 
how many steps the computer needed to arrive 
at a certain point. TRON will be more interesting 
if you pick a program with many branches, such 
as GOTO, GOSUB and IF-THEN-line number. 
Type TROFF to turn trace mode off before con- 
tinuing. 
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You don't have to trace an entire progrann. You 
can place IRON within a progrann as a line prior 
to the program section causing problenns. Put 
the word TROFF as a progrann line after the trou- 
blesome section. When you run the program, 
only the lines between IRON and TROFF will be 
bracketed in the results. 



Windows are a specific area of the screen that you define as your 
workspace. Everything you type (lines you type, listings of programs, 
etc.) after setting a window appears within the window's boundaries, 
not affecting the screen outside the window area. The Commodore 
128 provides two methods of creating windows: the WINDOW com- 
mand and ESCAPE key functions. 



Using tlie WINDOW Command to Create a Window 

The Commodore 128 BASIC 7.0 language features a command that 
allows you to create and manipulate windows: the WINDOW com- 
mand. The command format is: 

WINDOW top-left column, top-left row, bottom-right column, 
bottom-right row [,clear option] 

The first two numbers after WINDOW specify the column and row 
number of where you want the lop left corner of the window to be; 
the next two numbers are the coordinates for the bottom right cor- 
ner. Remember that the screen format (40 or 80 columns) dictates 
the acceptable range of these coordinates. You can also include a 
clear option with this command. If you add 1 to the end of the com- 
mand, the window screen area is cleared, as in this example: 

WINDOW 10, 10, 20, 20, 1 

Here's a sample program that creates four windows on the screen, in 
either 40- or 80-column format. 



USING 0128 MODE— Some BASIC Commands and Keyboard Operations Unique to 
86 C128 Mode 



u 



u 

u 
u 
u 
u 
u 
u 
u 

Li 

u 
u 
u 



10 PRINT"|j|" :REM CLEAR THE SCREEN 

20 A$="ABCDEFGHIJKLMNOPQRSTUVWXYZ" 

30 B$=A$+A$+A$ 

40 FOR I=1T0 25 :PRINT B$:NEXT :REM FILL SCREEN WITH CHARACTERS 

50 WINDOW 1 ,1 ,8 ,20 :REM DEFINE WINDOW 1 

60 PRINT"£R" 

63 REM THE PREVIOUS LINE FILLS WINDOW 1 WITH RED 

65 REM HOLD DOWN <CONTROL> THEN PRESS THE 3 KEY (RED) TO GET THE "£" CHARACTER 

67 REM HOLD DOWN <CONTROL> THEN PRESS THE 9 KEY (RVS ON) TO GET THE "R" CHAR 

80 WINDOW 15,15,39,20,1 :REM DEFINE 2ND WINDOW 

90 PRINT "^"; B$;A$ :REM FILL WINDOW WITH CHARACTERS 

95 REM HOLD DOWN <CONTROL> THEN PRESS THE 6 KEY (GREEN) TO GET THE "2" CHARACTER 

100 WINDOW 30,1,39,22,1 :REM DEFINE 3RD WINDOW 

110 PRINT"!": LIST :REM SELECT YELLOW AND LIST IN WINDOW 

115 REM HOLD DOWN <CONTROL> THEN PRESS THE 8 KEY (YELLOW) TO GET THE "2" GHAR 

120 WINDOW 5,5,33,18,1 :REM DEFINE 4TH WINDOW ON TOP OF THE OTHER THREE 

130 PRINT"a":PRINTA$:LIST: REM CHANGE COLOR - PRINT A$ AND LIST IN WINDOW 

140 REM HOLD DOWN <COMMODORE> THEN PRESS THE 1 KEY (ORANGE) TO GET THE "^" CHAR 

150 REM IN 80 COLUMN MODE THE "a" CHAR DISPLAYS PURPLE 

160 REM ALL COLOR CHANGE CHARACTERS ARE ONLY DISPLAYED WITHIN QUOTES 
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Using the ESC Key to Create a Window 

To set a window with tine ESC (Escape) Key, follow these steps: 

1. Move the cursor to the screen position you want as the top 
left corner of the window. 

2. Press the ESC key and release it, and then press T. 

3. Move the cursor to the position you want to be the bottom 
right corner of the window. 

4. Press ESC and release, then B. Your window is now set. 

You can nnanipulate the window and the text inside using the ESC 
key Screen editing functions, such as inserting and deleting text, 
scrolling, and changing the size of the window, can be performed by 
pressing ESC followed by another key To use a specific function, 
press ESC and release it. Then press any of the following keys listed 
for the desired function: 
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@ Erase everything from cursor to end of screen window 

A Automatic insert nnode 

B Set tine bottom rigiit corner of the screen window (at the 

current cursor location) • , 

C Cancel insert mode i i 

D Delete current line 

E Set cursor to non-flashing mode , . 

F Set cursor to flashing mode i i 

G Enable bell (by Control-G) 

H Disable bell > 

I Insert a line { ! 

J Move to the beginning of the current line 

K Movetotheendof the current line ^ . 

L Turn on scrolling \ I 

M Turn off scrolling 

N Return to normal (non-reverse video) screen display , 

(80-column only) I I 

O Cancel quote mode 

P Erase everything from the beginning of line to the cursor 

Q Erase everything from the cursor to the end of the line \ [ 

R Reverse video screen display (80-column only) 

S Change to block cursor (■) (80-column only) 

T Set the top left corner of the screen window (at the current | j 

cursor location) 
U Change to underline cursor (_) (80-column only) 

V Scroll screen up one line j \ 

W Scroll screen down one line 

X Toggle between 40 and 80 columns 

Y Restore default TAB stops ] { 

Z Clear all TAB stops 

Experiment with the ESCape key functions. You will probably find ! \ 

certain functions more useful than others. Note that you can use the 
usual INST/DEL key to perform text editing inside a window as well. 

When a window is set up, all screen output is confined to the "box" 
you have defined. If you want to clear the window area, press SHIFT 
and CLEAR/HOME together. To cancel the window, press the CLEAR/ [_| 
HOME key twice. The window is then erased, and the cursor is posi- 
tioned in the top left corner of the screen. Windows are particularly 

useful in writing, listing and running programs because they allow | j 

you to work in one area of the screen while the rest of the screen 
stays as is. 

u 
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2 MHz 
Operation 



PI Keys Unique To 



C128Nlode 



Tlie FAST and SLOW Commands 

The 2 MHz operating mode allows you to run non-graphic programs 
in 80-column format at twice the normal speed. You can switch nor- 
mal and fast operation by using the FAST and SLOW commands. 

The FAST command places the Commodore in 2 MHz mode. The 
format of this command is: 

FAST 

The SLOW command returns the Commodore 128 to 1 MHz mode. 
The default speed for the Commodore 128 microprocessor (8502) is 
1 MHz. The format of this command is: 

SLOW 

Function Keys 

The four keys on the Commodore 128 keyboard on the right side 
above the numeric keypad are special function keys that let you save 
time by performing repetitive tasks with the stroke of just one key 
The first key reads F1/F2, the second F3/F4, the third F5/F6, and the 
last F7/F8. You can use functions keys 1 , 3, 5, 7 by pressing the key 
by itself. To use function keys 2, 4, 6 and 8, press SHIFT along with 
the function key 



Here are the standard functions for each key: 



F1 
GRAPHIC 

F5 
DSAVE" 



F2 
DLOAD" 

F6 
RUN 



F3 
DIRECTORY 

F7 
LIST 



F4 
SCNCLR 

F8 
MONITOR 
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Here's what each function involves: 

KEY 1 enters one of the GRAPHICS modes when you supply 
the number of the graphics area and press RETURN. 
The GRAPHICS command is necessary for giving graph- 
ics commands such as CIRCLE or PAINT For more on 
GRAPHICS, see Section 6. 

KEY 2 prints DLOAD " on the screen. All you do is enter the 
program name and end quotes and hit RETURN to load 
a program from disk, instead of typing out DLOAD your- 
self. 

KEY 3 lists a DIRECTORY of files on the disk in the disk drive. 

KEY 4 clears the screen using the SCNCLR command. 
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KEY 5 prints DSAVE " on the screen. All you do is enter the 
program name, and press RETURN to save the current 
program on disk. 
KEY 6 RUNS the current program. j ^ 

KEY 7 displays a LISTing of the current program. c— ' 

KEY 8 lets you enter the Machine Language Monitor. See 

Appendix J for a description of the Monitor. ^ . 



Redefining Function Keys ^ i 

You can redefine or program any of these l<eys to perform a function 
that suits your needs. Redefining is easy using the KEY command. 
You can redefine the keys from BASIC programs, or change them at | J 

any time in direct mode. A situation where you might want to rede- 
fine a function key is when you use a command frequently and want 
to save time instead of repeatedly typing in the command. The new l { 

definitions are erased when you turn off your computer. You can 
redefine as many keys as you want and as many times as you want. 

M 

If you want to reprogram the F7 function key to return you to text ' — 

mode from high-resolution or multicolor-graphic modes, for example, 

you would use the key command in this fashion: I j 

KEY 7,"GRAPHIC 0" -^ CHR$(13) 

CHR$(1 3) is the ASCII code character for RETURN. So when you || 

press the F7 key after redefining the key what happens is the com- ' — 
mand "GRAPHIC 0" is automatically typed out and entered into the 

computer with RETURN. Entire commands or series of commands j [ 
may be assigned to a key 



Otiier Keys Used in CI 28 IMode Only "-" 

Help As noted previously when you make an error in 1 ( 

a program, your computer displays an error 
message to tell you what you did wrong. These 

error messages are further explained in Appen- \ I 

dix A of this manual. You can get more assis- 
tance with errors by using the HELP key After 

an error message, press the HELP key to locate LJ 
the exact point where the error occurred. When 

u 
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you press HELR the line with the error is high- 
lighted on the screen in reverse video (in 40 
colunnn), or underlined (in 80 colunnn output). 
For exannple: 

7SYNTAX ERROR IN LINE 10 Your computer 

displays this. 

HELP You press HELR 

10 FRONT "COMMODORE COMPUTERS" 

The line with the mistake is highlighted in 
reverse if in 40-column output, or underlined 
in 80-column output. 
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No Scroll Press this key down to stop the text from scroll- 

ing when the cursor reaches the bottonn of the 
screen. This turns off scrolling until you press 
the NO SCROLL key again. 

Caps Lock When the keyboard is in upper/lower case 

nnode, this key lets you type in all capital letters 
without using the SHIFT key The CAPS LOCK 
key locks when you press it, and must be 
pressed again to be released. CAPS LOCK only 
affects the lettered keys. 

40/80 Display The 40/80 key selects the main (default) screen 
format: either 40 or 80 column. The selected 
screen displays all messages and output at 
power-up, or when RESET, reset or RUN/STOP/ 
RESTORE are used. This key may be used to set 
the display format only before turning on or 
resetting the computer. You cannot change 
modes with this key after the computer is 
turned on. Section 8 provides an explanation of 
40/80 column modes. 

Alt The ALT key allows programs to assign a special 

meaning to a given key or set of keys. 

Unless a specific application program redefines 
it, holding down the ALT key and any other key 
has no additional effect. 
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Tab This key works like the TAB key on a typewriter. i^ / 

It may be used to move the cursor to the next '^ — 1 
tab position. Tabs are set every 8th column 

starting from column 1 . j f 

Line Feed Pressing this key advances the cursor to the 

next line, similar to a cursor down key ! ( 



***••**••*****•••**••*•******•••••***••*•••*******••••»: 



\ 



This section covers only some of tlie concepts, /ceys and commands 

tliat make the Commodore 128 a special machine. You can find 

further explanations of the BASIC language in the BASIC 7. \^ 

Encyclopedia in Chapter V 
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The CHAR Command 1 04 
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Using Sprite Statements in a Program 112 
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Turning on Sprites 115 
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p^ Graphics 

Overview 
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In C128 mode, the Commodore 128 BASIC 7.0 language provides 
many new and powerful commands and statements that make 
graphics programming much easier. Each of the two screen formats 
available in C128 mode (40 columns and 80 columns) is controlled by 
a separate microprocessor chip. The 40-column chip is called the 
Video Interface Controller, or VIC for short. The 80-column chip is 
referred to as the 8563. The VIC chip provides 16 colors and controls 
all the highly detailed graphics called bit-mapped graphics. The 80- 
column chip, which also offers 16 colors, displays characters and 
character graphics. The new BASIC graphics commands are not 
supported in 80 column output, though you can program the 80 
column chip to support a bit map display with your own machine 
language programs. Thus, all detailed BASIC graphic programs in 
C128 mode must be done in 40-column format. 



Grapiiics Features 

As part of its impressive C128 mode graphics capabilities, the Com- 
modore 128 provides: 

• 13 specialized graphics commands 

• 16 colors 

• Six different display modes 

• Eight programmable movable objects called SPRITES 

• Combined graphics/text displays 

All these features are integrated to provide a versatile, easy-to-use 
graphics system. 
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Command Summary 

Here is a brief explanation of each graphics comnnand: 

BOX — Draws rectangles on the bit-nnap screen 
CHAR — Displays characters on the bit-nnap screen 
CIRCLE — Draws circles, ellipses and other geonnetric 

shapes 
COLOR — Selects colors for screen border, foreground, 

background and characters 
DRAW — Displays lines and points on the bit-nnap screen 
GRAPHIC — Selects a screen display (text, bit nnap or split- 
screen bit nnap) 
GSHAPE — Retrieves the text-string variable stored by 

SSHAPE 
MOVSPR — Positions or nnoves sprites on screen 
PAINT — Fills area on the bit-nnap screen with color 
SCALE — Sets the relative size of the images on the bit-map 

screen 
SPRDEF — Enters sprite definition mode to edit sprites 
SPRITE — Enables, colors, sets sprite screen priorities, and 

expands a sprite 
SPRSAV — Stores a text string variable into a sprite storage 

area and vice versa 
SSHAPE — Stores the image of a portion of the bit-map 

screen into a text-string variable 

Most of these commands are described in the examples in this sec- 
tion. See Chapter V, BASIC 7.0 Encyclopedia, for detailed format and 
information on all graphics commands and functions, including those 
not discussed in this section. 
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Graphics 
Programming on 
theC128 



The following section describes a step-by-step grapliics program- 
ming example. As you learn eacin graphics command, add it to a 
program you will build as you read this section. When you are fin- 
ished, you will have a complete graphics program. 



Clioosing Coiors 

The first step in graphics programming is to choose colors for the 
screen background, foreground and border. To select colors, type: 

COLOR source, color 

where source is the section of the screen you are coloring (back- 
ground, foreground, border, etc.), and color is the color code for the 
source. See Figure 6-1 for source numbers. Figure 6-2 for 40- 
column-format color numbers, and Figure 6-3 for 80-column-format 
color numbers. 



Number 



Source 






40-column background color (VIC) 




1 


Foreground for the graphics screen 


(VIC) 


2 


Foreground color 1 for the multicolor screen (VIC) 


3 


Foreground color 2 for the multicolor screen (VIC) 


4 


40-column (VIC) border (whether in text or graphics 




mode) 






5 


Character color for 40- or 80-column text screen 


6 


80-column background color (8563) 






Figure 6-1. 


Source Numbers 




Color Code 


Color 
Black 


Color Code 
9 


Color 


1 


Orange 


2 


White 


10 


Brown 


3 


Red 


11 


Light Red 


4 


Cyan 


12 


Dark Gray 


5 


Purple 


13 


Medium Gray 


6 


Green 


14 


Light Green 


7 


Blue 


15 


Light Blue 


8 


Yellow 


16 


Light Gray 



Figure 6-2. Color Numbers in 40-Column Output 



97 



USING C128 MODE— Color, Animation and Sprite Graphics Statements 



lypes of Screen 
Display 



Color Code 


Color 


Color Code 

9 

10 


Color 


1 
2 


Black 
White 


Dark Purple 
Dark Yellow 


3 
4 
5 
6 
7 
8 


Dark Red 
Light Cyan 
Light Purple 
Dark Green 
Dark Blue 
Light Yellow 


11 
12 
13 
14 
15 
16 


Light Red 
Dark Cyan 
Medium Gray 
Light Green 
Light Blue 
Light Gray 



Figure 6-3. Color Numbers in 80-Column Output 



Your C128 has several different ways of displaying information on the 
screen; the parameter "source" in the COLOR command pertains to 
different modes of screen display The types of video display fall into 
four categories. 

The first one is text display which displays only characters, such as 
letters, numbers, special symbols and the graphics characters on 
the front faces of most 01 28 keys. The 01 28 can display text in both 
40-column and 80-column screen formats. 

The second and third categories of display modes are used for highly 
detailed graphics, such as pictures and intricate drawings. This type 
of display mode includes standard bit-map mode and multicolor bit- 
map mode. Bit-map modes allow you to control each and every indi- 
vidual screen dot or pixel (picture element). This allows consid- 
erable detail in drawing pictures and other computer art. These 
graphic displays are only available in 40-column format. The 
80-column display is dedicated to text display 

The difference between text and bit-map modes lies in the way in 
which each screen addresses and stores information. The text 
screen can only manipulate entire characters, each of which covers 
an area of 8 by 8 pixels on your screen. The more powerful bit-map 
mode exercises control over each and every pixel on your screen. 

The fourth type of screen display split screen, is a mixture of the first 
two types. The split-scren display outputs part of the screen as text 
and part in bit-map mode (either standard or multicolor). The 0128 is 
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capable of this because it uses two separate parts of the computer's 
memory to store the two screens: one part of the text, and the other 
for the graphics screen. 

Type the following short program: 

10 COLOR 0,1: REM TEXT BACKGROUND COLOR = BLACK 
20 COLOR 1,3: REM FOREGROUND COLOR FOR BIT MAP 

SCREEN = RED 
30 COLOR 4,1: REM BORDER COLOR = BLACK 

This example colors the background black, the foreground red and 
the border black. 



Selecting the Graphic IMcde 

The next graphics programming step is to select the appropriate 
graphic mode. This is done using the GRAPHIC command, whose 
format is as follows: 

GRAPHIC Mode [,c]I,s] or GRAPHIC CLR 

where mode is a digit between and 5, c is either a or 1 and s is a 
value between and 25. Figure 6-4 shows the values corresponding 
to the graphic modes. 



Mode 


Description 





40-column standard text 


1 


Standard bit map 


2 


Standard bit map (split screen) 


3 


Multicolor bit map 


4 


Multicolor bit map (split screen) 


5 


80-column text 



Figure 6-4. Graphic Modes 

The parameter c stands for CLEAR. Figure 6-5 explains the values 
associated with CLEAR. 

Value Description 

Do not clear the graphics screen 

1 Clear the graphics screen 

Figure 6-5. CLEAR Parameters 



n 
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When you first run your progrann, you will want to clear the graphics j [ 

screen for the first time, so set c equal to 1 in the GRAPHIC com- 
mand. If you run it a second time, you may want to leave your picture 
on the screen, instead of drawing it all over again. In this case, set c I j 

equal to 0. 



The s parameter specified where the start of the text screen in split- 
screen mode is to begin at the line after the specified line number. If 
you omit the s parameter and select a split-screen graphic mode (2 
or 4), the text screen portion is displayed in rows 20 through 25; the 
rest of the screen is bit mapped. The s parameter allows you to 
change the starting line of the text screen to any line on the screen, 
ranging from 1 through 25. A zero as the s parameter indicates the 
screen is not split, and is all text. 

The final GRAPHIC command parameter is CLR. When you first 
issue a bit-map graphic command, the Commodore 128 allocates a 
9K area for your bit-mapped screen information. 8K is reserved for 
the data for your bit map and the additional 1 K is dedicated for the 
color data (video matrix). Since 9K is a substantial block of memory 
you may want to use it again for another purpose later on in your 
program. This is the purpose of CLR. It reorganizes the Commodore 
1 28 memory and gives you back the 9K of memory that was dedi- 
cated to the bit-map screen, so you can use it for other purposes. 

The format for CLR is as follows: 

GRAPHIC CLR 

When using this format, omit all other GRAPHIC command 
parameters. 

Add the following command to your program. It places the C128 in 
standard bit-map mode and allocates an 8K bit-map screen (and 1 K 
of color data) for you to create graphics. 

40 GRAPHIC 1,1 

The second 1 in this command clears the bit-map screen. If you do 
not want to clear the screen, change the second 1 to (or omit it 
completely). 



u 
u 

LI 
U 
U 
U 

u 
u 
u 
u 

u 



NOTE: If you are in bit-map mode and are unable to return to — I 

the text screen, press the RUN/STOP and RESTORE keys at the 

same time, or press the ESC key followed by X, to return to the | , 
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80-column screen. Even though you can only display graphics 
with the VIC (40-colunnn) chip, you can still write graphics pro- 
grams in 80"COlumn fornnat. If you have the Connnnodore 1902 
dual nnonitor and you want to view your graphics program while 
it is running, you must select the 40-column output by switching 
the slide switch on the monitor to 40-column output. 

Displaying Graphics on tiie Screen 

So far, you have selected a graphics mode and the colors you want. 
Now you can start displaying graphics on the screen. Start with a 
circle. 

Drawing a To draw a circle, use the CIRCLE statement as 

Circle— The follows: 

CIRCLE 

Command 



60 CIRCLE 1, 150, 100,40,40 



This displays a circle in the center of the screen. The CIRCLE state- 
ment has nine parameters you can select to achieve various types of 
circles and geometric shapes. For example, by changing the num- 
bers in the CIRCLE statement in line 60 you can obtain different size 
circles or variations in the shape (e.g., an oval). The CIRCLE state- 
ment adds power and versatility in programming Commodore 128 
graphics in BASIC. The meaning of the numbers in the CIRCLE state- 
ment is explained under the CIRCLE listing in Chapter V, BASIC 7.0 
Encyclopedia. 

On your Commodore 1 28 screen, the point where X = and Y = 
is at the top left corner of the screen, and is referred to as the HOME 
position. In standard geometry however, the point where X and Y 
both equal is the bottom left corner of a graph. Figure 6-6 shows 
the arrangement of the X (horizontal) and Y (verticle) screen coordi- 
nates and the four points at the corners of the CI 28 screen. 



0,0 



Y Coordinate 



X Coordinate 



0,199 



319,0 



319,199 
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Figure 6-6. Arrangement of X and Y Coordinates 
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Drawing a Box— 
The BOX 
Command 



Now try a box. To draw a box, type: 
80 BOX1,20,100,80,160,90,1 



This draws a solid box to the left of the circle. To find out what the 
numbers in the box statennent mean, consult Chapter V, BASIC 7.0 
Encyclopedia. The BOX statement has seven parameters you can 
select and modify to produce different types of boxes. Change the 
foreground color and draw the outline of a box to the right of the CIR- 
CLE with these statements: 

90 C0L0R1,9:REM CHANGE FOREGROUND COLOR 
100 BOX1,220,100,280,160,90,0 

Experiment with the BOX statement to produce different variations 
of rectangles and boxes. 



Drawing Lines, 

Points and 

Other Shapes— 

The 

DRAW Command 



You now know how to select graphic modes and 
colors and how to display circles and boxes on 
the screen. Another graphics statement, DRAW, 
lets you draw lines on the screen just as you 
would with a pencil and a piece of paper. The 
following statement draws a line below the 
boxes and circle. 

120 DRAW 1,20,180 TO 280,180 



Here's what the numbers mean: 

• 1 is the color source (in this case the foreground) 

• 20 is the starting X (horizontal) coordinate 

• 1 80 is the starting Y (verticle) coordinate 

• 280 is the ending horizontal coordinate 

• 1 80 is the ending verticle screen coordinate. 

To erase a drawn line, change the source (1) in the DRAW statement 
to 0. The line is drawn with the background color which erases the 
line. Try using different coordinates and other sources to become 
accustomed to the DRAW statement. 

The DRAW statement can take another form that allows you to 
DRAW a line, change direction and then DRAW another line, so the 
lines are continuous. For example, try this statement: 

130 DRAW 1,10,20 TO 300,20 TO 150,80 TO 10,20 

This statement DRAWs a triangle on the top of the scren. The four 
pairs of numbers represent the X and Y coordinates for the three 
points of the triangles. Notice the first and last coordinates are the 
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same, since you must finish drawing tlie triangle on the same point 
you started. This form of draw statement gives you the power to 
DRAW almost any geometric shape, such as trapezoids, parallelo- 
grams and polygons. 

The DRAW statement also has a third form. 

You can DRAW one point at a time by specifying the starting X and Y 
values as follows: 

150 DRAW 1,150,175 

This statement DRAWs a dot below the CIRCLE. 

As you can see, the DRAW statement has versatile features which 
give you the capability to create shapes, lines points and a virtually 
unlimited number of computer drawings on your screen. 
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PAINTing The DRAW statement allows you to outline 

Outlined areas on the screen. What if you want to fill 

Areas— The areas within your drawn lines? That's where the 

PAINT Command RM NT statement comes i n . The PA! NT state- 
ment does exactly what the name implies — it 
fills in, or PAINTs, outlined areas with color. Just 
as a painter covers a canvas with paint, the 
RMNT statement covers the areas of the screen 
with any of the 1 6 colors. For example, type: 

160 PAINT 1,150,97 

Line 160 RMNTS the circle you have drawn in line 60. The RMNT 
statement fills a defined area until a specified boundary is detected 
according to which source is indicated. When the Commodore 1 28 
finishes PAINTing, it leaves the pixel cursor at the point where PAINT- 
ing began (in this case, at point 150,97). 

Here are two more PAINT statements: 

180 PAINT 1,50,25 
200 PAINT 1,225,125 

Line 1 80 PAINTS the triangle and line 200 PAINTS the empty box. 

*IMPORTANT PAINTING TIP: If you choose a starting point in 
your PAINT statement which is already colored from the same 
source, the Commodore 128 will not PAINT that area. You must 
choose a starting point which is entirely inside the boundary of 
the shape you want to PAINT The starting point cannot be on 
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the boundary line of a pixel that is colored from the same 
source. The source numbers of the screen coordinate and the 
coordinate specified in the PAINT command must be different. 



Displaying Cliaracters on a Bit IMapped Screen— The CHAR 
Command 
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So far, the example program has operated in standard bit map mode. 
Bit map mode uses a completely different area of memory to store 

the screen data than text mode (the mode in which you enter pro- j 1 

grams and text). If you enter bit map mode, and try to type charac- 
ters onto the screen, nothing happens. This is because the charac- 
ters you are typing are being displayed on the text screen and you [ j 
are looking at the bit map screen. Sometimes it is necessary to dis- 
play characters on the bit map screen, when you are creating and 
plotting charts and graphs. The CHAR command is designed espe- j I 
cially for this purpose. To display standard characters on a bit map 
screen, use the CHAR statement as follows: 

220 CHAR 1, 11,24,"GRAPHICS EXAMPLE" U 

This displays the text "GRAPHICS EXAMPLE" starting at line 25, 

column 1 2. The CHAR command can also be used in text mode, j j 

however, it is primarily designed for the bit map screen. 
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Changing the Size of Graphic images— 
The SCALE Command 

The Commodore 128 has another graphics statement which offers 
additional power to your graphics system. The SCALE statement 
offers the ability to scale up (enlarge) or scale down (reduce) the size 
of graphic images on your screen. The SCALE statement also 
accomplishes another task, which can be explained as follows. 

In standard bit-map mode, the 40-column screen has 320 horizontal I I 

coordinates and 200 vertical coordinates. In multicolor bit map 

u 
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mode, the 40-column screen has only half the horizontal resolution 
of standard bit nnap nnode, that is, 160 by 200. This reduction in reso- 
lution is connpensated for by the additional capability of using one 
additional color for a total of three colors, within an 8 by 8 character 
nnatrix. Standard bit nnap mode can only display two colors within an 
8 by 8 character matrix. 

The SCALE command allows you to size your graphic images on a 
scale of 0-32767 in both the X and Y directions, instead of only the 
320 by 200 default scale. 

To SCALE your screen, type: 

SCALE 1, X, y 

and the screen coordinates range from to 32767 whether you are 
in standard or multicolor high-res mode. The default for SCALing is 
1 023 by 1 023 if X and Y are not specified in the SCALE command. 
To turn off SCALEing, type: 

SCALE 

and the coordinates return to their normal values. 
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Creating a Sample Graphics Program 

So far, you have learned several graphics statements. Now tie the 
progrann together and see how the statements work at the same 
time. Here's how the program looks now. The color statements in 
lines 70, 110, 140, 170, 190 and 210 are added to display each object 
in a different color. 



10 COLOR 0,1 :REM SELECT BKGRND COLOR 

20 COLOR 1,3 :REM SELECT FORGRND COLOR 

30 COLOR 4,1 :REM SELECT BORDER COLOR 

40 GRAPHIC1,1:REM SELECT STND HI RES 

60 CIRCLE ,150,130,40,40:REM CIRCLE 

7,0 COLOR 1,6 : REM CHANGE FQRGRND COLOR 

,80 BOX, 20, 100,80, 160,9b,l:REM BOX 

90 COLOR 1,9 :REM CHANGE FORGRND COLOR 

100 BOX, 220, 100,280, 160, 90, 0:REM BOX 

110 COLOR 1,8 :REM CHANGE FORGRND COLOR 

120 DRAW 1,20,180 TO 280,180:REM DRAW LINE 

130 DRAW 1,10,20 TO 300,20 TO150,80 TO 10,20: REM DRAW TRIANGLE 

140 COLOR 1,15 :REM CHANGE FORGRND COLOR 

150 DRAW 1 ,150,175:REM DRAW 1 POINT 

160 PAINT 1,150,97:REM PAINT CIRCLE 

170 COLOR 1,5 -:REM CHANGE FORGRND COLOR 

180 PAINT 1,50,2 5:REM PAINT TRIANGLE 

190 COLOR 1,7 :REM CHANGE FORGRND COLOR 

200 PAINT 1,225,125:REM PAINT BOX 

210 COLOR 1,11 :REM CHANGE FORGRND COLOR 

220 CHAR, 11, 24, "GRAPHICS EXAMPLE":REM DISPLAY TEXT 

230 FORI=lTO5d0;0:NEXT: GRAPHIC , 1 : COLOR 1,2 



Here's what the program does: 

• Lines 10 through 30 select a COLOR for the background, fore- 
ground and border, respectively 

• Line 40 chooses a graphic mode. 

• Line 60 displays a CIRCLE. 

• Line 80 DRAWs a colored-in BOX. 

• Line 1 00 DRAWs the outline of a box. 

• Line 1 20 DRAWs a straight line at the bottom of the screen. 

• Line 1 30 DRAWs a triangle. 

• Line 1 50 DRAWs a single point below the CIRCLE. 

• Line 160 PAINTs the circle. 

• Line 180 PAINTs the triangle. 

• Line 200 RMNTs the empty box. 
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• Line 220 prints the CHARacters "GRAPHICS EXAMPLE" at 
tine bottonn of the screen. 

• Line 230 delays the program so you can watch the graphics 
on the screen, switches back to text mode and colors the 
characters black. 

If you want the graphics to remain on the screen, omit the GRAPHIC 
statement in line 230. 

Here are some additional example programs using the graphics 
statements you just learned. 



f \ 



n 



n 



10 COLOR 0,1 

20 COLOR 1,8 

30 COLOR 4,1 

40 GRAlPHICl,l 

50 PORI=80TO240 STEPlO 

60 CIRCLEl,Irl00,75,75 

70 NEXT 

80 COLOR 1,5 

90 PORI=80TO250 STEPlO 

100 CIRCLEl, I, 100,50,50 

110 NEXT 

120 COLOR 1,7 

130 FORI=50TO280 STEPlO 

140 CIRCLEl,!, 100,25,25 

150 NEXT 

160 FORI=lTO7500 : NEXT ;GRAPHICO ,1 jGOLORl , 2 



( ) 



n 



n 
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10 GRAPHIC 1,1 

20 COLORO,1 

30 C0L0R4,1 

40 PORi=lTO50 

50 Z=INT{((RND(1))*16)+1)* 1 

60 C0L0R1,Z 

70 X=INT({(RND(1))*30)+1)*10 

80 Y=INT(((RND(1))*20)+1)*10 

90 U=INT(((RND(1))*30)+1)*10 

100 V=INT(((RND(1))*20)+1)*10 

110 DRAW,X,Y TO U,V 

120 NEXT 

130 SCNCLR 

140 GOTO40 



n 
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10 C0L0R4 , 7 : COLORO \ 7 : COLORl , 1 

20 GRAPHIC iM 

30 #ORI= 400TO1 STEP -5 

40 DRAW 1 r 150 r 100 TO 1,1 

50 NEXT - 

60 PORt= lTO4d0 STEP 5 

70 DRAW l,150ri00 TO 1,1 

80 NEXT 

90 FORI* 4dT0 320 STEP 5 

100 DRAW 1,150,100 TO 1,320 

110 NEXT 

120 FORI* 320TO30STEP -5 

130 DRAW 1,150,100 TO 320,1 

140 NEXT 

1 50 PORI=1T07500 : NEXT iGRAPHICO , 1 : COLORl , 1 



u 
u 






1 / 



Type the examples into your computer. RUN and SAVE them for 
future reference. One of the best ways to learn programming is to 
study program examples and see how the statements perform their 
functions. You'll soon be able to use graphics statements to create 
impressive graphics with your Commodore 1 28. 

If you need more information on any BASIC statement or command, 
consult the Chapter V, BASIC 7.0 Encyclopedia. 

You now have a set of graphic commands that allow you to create an 
almost unlimited number of graphics displays. But Commodore 1 28 
graphics abilities do not end here. The Commodore 128 has another 
set of statements, known as SPRITE graphics, which make the crea- 
tion and control of graphic images fast, easy and sophisticated. 
These high-level statements allow you to create sprites — moveable 
graphic objects. The CI 28 has its own built-in SPRite DEFinition abil- 
ity These statements represent the new technology for creating and 
controlling sprites. Read the next section and take your first step in 
learning computer animation. 



u 
u 
u 
u 
u 



u 



\ ^ 



I > 



108 



USING C128 MODE— Color, Animation and Sprite Graphics Statements 



\ I 



U 



n 



r— I 
I \ 

( — ^ 
I ^ 

n 
n 



n 



i ) 



Sprites: 
Programmable, 
Movable Objeot 
Blooks 



You already have learned about some of the Commodore 128's 
exceptional graphics capabilities. You've learned how to use the first 
set of high level graphics statements to draw circles, boxes, lines and 
dots. You have also learned how to color the screen, switch graphic 
modes, paint objects on the screen and scale them. Now it's time to 
take the next step in graphics programming — sprite animation. 

If you have worked with the Commodore 64, you already know some- 
thing about sprites. For those of you who are not familiar with the 
subject, a sprite is a movable object that you can form into any 
shape or image. You can color sprites in 16 colors. Sprites can even 
be multicolor. The best part is that you can move them on the 
screen. Sprites open the door to computer animation. 

Sprite Creation 

The first step in programming sprites is designing the way the sprite 
looks. For example, suppose you want to design a rocket ship or a 
racing car sprite. Before you can color or move the sprite, you must 
first design the image. In C128 mode, you can create sprites in these 
three ways: 

1 . Using SPRite DEFinition mode (SPRDEF) 

2. Using the new SPRITE statements within a program 

3. Using the same method as the Commodore 64. 

Sprite Definition Mode— The SPRDEF Command 

The Commodore 128 has a built-in SPRite DEFinition mode which 
enables you to create sprites on your Commodore 128. You may be 
familiar with the Commodore 64 method of creating sprites, in which 
you are required to either have an additional sprite editor, or design a 
sprite on a piece of graph paper and then READ in the coded sprite 
DATA and POKE it into an available sprite block. With the new Com- 
modore 128 sprite definition command SPRDEF, you can construct 
and edit your own sprites in a special sprite work area. 

To enter SPRDEF mode, type: 

SPRDEF 

and press RETURN. The Commodore 128 displays a sprite grid on 
the screen. In addition, the computer displays the prompt: 

SPRITE NUMBER? 

Enter a number between 1 and 8. The computer fills the grid and 
displays the corresponding sprite in the upper right corner of the 
screen. From now on, we will refer to the sprite grid as the work area. 
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The work area has the dimensions of 24 characters wide by 21 char- 
acters tall. Each character position within the work area corres- I J 

ponds to 1 pixel within the sprite, since a sprite is 24 pixels wide by 

21 pixels tall. While within the work area in SPRDEF mode, you have ^ 

several editing commands available to you. Here's a summary of the < I 

commands on the following page: 

Sprite Definition IViode Command Summary M 

CLR key— Erases the entire work area 

M key— Turns on/off multicolor sprite ; . 

CTRL 1-8- Selects sprite foreground color 1-8 LJ 
C- 1-8— Selects sprite foreground color 9-16 

1 key— Sets the pixel at the current cursor location to the i ) 
background color uJ 

2 key— Sets the pixel at the current cursor location to the 
foreground color ^ . 

3 key— Sets the pixel at the current cursor location to < ! 

multicolorl 

4 key— Sets the pixel at the current cursor location to ( i 
multicolor2 LJ 
A key— Turns on/off automatic cursor movement 

CRSR keys— Moves the cursor ( + ) within the work area ^ , 

RETURN— moves cursor to the start of the next line O 
HOME key— Moves cursor to the top left corner of work area. 

X key— Expands sprite horizontally c i 

Y key— Expands sprite vertically i^ I 

Shift RETURN— Saves sprite from work area and returns to 

SPRITE NUMBER prompt , i 

C key— copies one sprite to another ^ — 1 
STOP key— Turns off displayed sprite and returns to 
SPRITE NUMBER prompt without changing the sprite 
RETURN key— (at SPRITE NUMBER prompt) Exits 
SPRDEF mode 



u 



Sprite Creation Procedure in SPRite DEFinition IMode | j 

Here's the general procedure to create a sprite in SPRite DEFinition 

mode: v I 

1 . Clear the work area by pressing the shift and CLR/HOME keys at 
the same time. 

2. If you want a multicolor sprite, press the M key and an additional ^ j 

cursor appears next to the original one. Two cursors appear 

since multicolor mode actually turns on two pixels for every one 

in standard sprite mode. This is why multicolor mode is only half | \ 

the horizontal resolution of standard high-res mode. 
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Select a color for your sprite. For colors between 1 and 8, hold 
down the CONTROL key and press a key between 1 and 8. To 
select color codes between 9 and 16, hold down the Connnno- 
dore (O) key and press a key between 1 and 8. 
Now you are ready to start creating the shape of your sprite. The 
numbered keys 1 through 4 fill in the sprite and give it shape. For 
a single color sprite, use the 2 key to fill a character position 
within the work area. Press the 1 key to erase what you have 
drawn with the 2 key If you want to fill one character position at a 
tinne, press the A key Now you have to move the cursor manually 
with the cursor keys. If you want the cursor to move automati- 
cally to the right while you hold it down, do not press the A key 
since it is already set to automatic cursor movement. As you fill 
in a character position within the work area, you can see the 
corresponding pixel in the displayed sprite turn on. Sprite editing 
occurs as soon as you edit the work area. 

In multicolor mode, the 3 key fills two character positions in the 
work area with the multicolor 1 color, the 4 key fills two character 
positions with the multicolor 2. 

You can turn off (color the pixel in the background color) filled 

areas within the work area with the 1 key In multicolor mode, the 

1 key turns off two character positions at a time. 

While constructing your sprite, you can move freely in the work 

area without turning on or off any pixels using the RETURN, 

HOME and cursor keys. 

At any time, you may expand your sprite in both the vertical and 

horizontal directions. To expand vertically press the Y key To 

expand horizontally press the X key To return to the normal size 

sprite display press the X or Y key again. 

When a key turns on AND off of the same control, it is referred to 
as toggling, so the X and Y keys toggle the vertical and horizontal 
expansion of the sprite. 

When you are finished creating your sprite and are happy with 
the way it looks, save it by holding down the SHIFT key and 
pressing the RETURN key The Commodore 128 SAVEs the sprite 
data in the appropriate sprite storage area. The displayed sprite 
in the upper right corner of the screen is turned off and control is 
returned to the SPRITE NUMBER prompt. If you want to create 
another sprite enter another sprite number and edit the new 
sprite just as you did with the first one. If you want to display the 
original sprite in the work area again, enter the original sprite 
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number. If you want to exit SPRITE DEFinition nnode, simply 
press RETURN at the SPRITE NUMBER prompt. 

8. You can copy one sprite into another with the "C" key 

9. If you do not want to SAVE your sprite, press the STOP key The 
Commodore 128 turns off the displayed sprite and returns to the 
SPRITE NUMBER prompt. 

10. To EXITSPRite DEFinition mode, press the RETURN key while 
the SPRITE NUMBER prompt is displayed on the screen when no 
sprite number follows it. You can exit under either of the follow- 
ing conditions: 



The SPRITE and MOVSPR commands are discussed in greater detail 
in the next section. 
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Immediately after you SAVE your sprite (shift RETURN), 
Immediately after you press the STOP key 

Once you have created a sprite and have exited SPRite DEFinition l-J 

mode, your sprite data is stored in the appropriate sprite storage 

area in the Commodore 128's memory Since you are now back in the . ^ 

control of the BASIC language, you have to turn on your sprite in 1 I 

order to see it on the screen. To turn it on again, use the SPRITE 

command. For example, you created sprite 1 in SPRDEF mode. To ^ . 

turn it on in BASIC, color it blue and expand it in both the X and Y [ i 

directions enter this command: 

SPRITE 1,1,7,0,1,1,0 [_j 

Now use the MOVSPR command to move it at a 90-degree angle at a 
speed of 5, as follows: 

MOVSPR 1, 90 # 5 



u 
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Now you know all about SPRDEF mode. First, create the sprite, save . . 

the sprite data and exit from SPRDEF mode to BASIC. Next turn on I 1 

your sprite with the SPRITE command. Move it with the MOVSPR 

command. When you're finished programming, SAVE your sprite , . 

data in a binary file with the BSAVE command. i I 

See Storing Sprite Data in Binary Files later in this section for ^ . 

more information on the BSAVE and BLOAD commands. . 1 
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Using Sprite Statements in a Program 

This method uses built-in statements so you don't have to use any 
aids outside your program to design your sprite, as the other two 
methods require. This method uses some of the graphics statements 
you learned in the previous section. Here's the general procedure. 
The details will be added as you progress. 

1 . Draw a picture with the graphics statements you learned in 
the last section, such as DRAW, CIRCLE, BOX and PAINT 
Make the dimensions of the picture 24 pixels wide by 21 pix- 
els tall in standard bit map mode or 12 pixels wide by 21 tall in 
multicolor bit map mode. 

2. Use the SSHAPE statement to store the picture data into a 
string variable. 

3. Transfer the picture data from the string variable into a sprite 
with the SPRSAV statement. 

4. Turn on the sprite, color it, select either standard or multi- 
color mode and expand it, all with the SPRITE statement. 

5. Move the sprite with the MOVSPR statement. 



Drawing the Sprite Image 

Here are the actual statements that perform the sprite operations. 
When you are finished with this section, you will have written your 
first sprite program. You'll be able to RUN the program as much as 
you like, and SAVE it for future reference. 

The first step is to draw a picture (24 by 21 pixels) on the screen 
using DRAW, CIRCLE, BOX or PAINT This example is performed in 
standard bit map mode, using a black background. Here's the state- 
ments that set the graphic mode and color the screen background 
black. 

5 COLOR 0,1 :REM COLOR BACKGROUND BLACK 
10 GRAPHIC 1,1 :REM SET STND BIT MAP MODE 

The following statements DRAW a picture of a racing car in the 
upper-left corner of the screen. You already learned these state- 
ments in the last section. 
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5 COLOR 0,1 






10 GRAPHIC 1,1 






15 BOX 1,2,2,45,45 






20 DRAW 1,17,10 TO 28,10 TO 26,30 TO 19,30 


TO 


17,10 :REM CAR BODY 


22 DRAW 1,11,10 TO 15,10 TO 15,18 TO 11,18 


TO 


11,10: REM UP LEFT WHEEL 


24 DRAW 1,30,10 TO 34,10 TO 34,18 TO 30,18 


TO 


30,10:REM RGHT WHEEL 


26 DRAW 1,11,20 TO 15,20 TO 15,28 TO 11,28 


TO 


11,20:REM LOW LFT WHEEL 


28 DRAW 1,30,20 TO 34,20 TO 34,28 TO 30,28 


TO 


30,20:REM LO RGHT WHEEL 


30 DRAW 1,26,28 TO 19,28 






32 BOX 1,20,14,26,18,90,1 






35 BOX 1,150, 35, 195, 40,90, 1:REM STREET 






37 BOX 1,150, 135, 195, 140, 90, 1:REM STREET 






40 BOX 1,150, 215, 195, 220, 90, 1:REM STRT 






42 BOX 1,50,180,300,194 






44 CHAR 1,18,23, "FINISH" 







RUN the program. You have just drawn a white racing car, enclosed 
in a box, in the upper-left corner of the screen. You have also drawn 
a raceway with a finish line at the bottonn of the screen. At this point, 
the racing car is still only a stationary picture. The car isn't a sprite 
yet, but you have just completed the first step in sprite 
programming — creating the image. 



Storing the Sprite Data witii SSHAPE 

The next step is to save the picture into a text string. Here's the 
SSHAPE statement that does it: 

45 SSHAPE A$,11,10,34,30:REM SAVE THE PICTURE IN A 
STRING 

The SSHAPE command stores the screen image (bit pattern) into a 
string variable for later processing, according to the specified 
screen coordinates. 

The numbers 11,10, 34, 30 are the coordinates of the picture. You 
must position the coordinates in the correct place or the SSHAPE 
statement can't store your picture data correctly into the string varia- 
ble A$. If you position the SSHAPE statement on an empty screen 
location, the data string is empty When you later transfer it into a 
sprite, you'll realize there is no data present. Make sure you position 
the SSHAPE statement directly on the correct coordinate. Also, be 
sure to create the picture with the dimensions 24 pixels wide by 21 
pixels tall, the size of a single sprite. 

The SSHAPE statement transfers the picture of the racing car into a 
data string that the computer interprets as picture data. The data 
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String, A$, stores a string of zeroes and ones in the connputer's menn- 
ory that nnake up the picture on the screen. As in ail computer graph- 
ics, the connputer has a way it can represent visual graphics with bits 
in its memory Each dot on the screen, called a pixel, has a bit in the 
computer's memory that controls it. In standard bit-map mode, if the 
bit in memory is equal to a 1 (on), then the pixel on the screen is 
turned on. if the controlling bit in memory is equal to a (off), then 
the pixel is turned off. 



Saving the Picture Data in a Sprite 

Your picture is now stored in a string. The next step is to transfer the 
picture data from the data string (A$) into the sprite data area so you 
can turn it on and animate it. The statement that does this is SPRSAV. 
Here are the statements: 

50 SPRSAV A$,1:REM STORE DATA STRING IN SPRITE 1 
55 SPRSAV A$,2:REM STORE DATA STRING IN SPRITE 2 

Your picture data is transferred into sprite 1 and 2. Both sprites have 
the same data, so they look exactly the same. You can't see the 
sprites yet, because you have to turn them on. 



Turning on Sprites 

The SPRITE statement turns on a specific sprite (numbered 1 
through 8), colors it, specifies its screen priority expands the sprite's 
size and determines the type of sprite display The screen priority 
refers to whether the sprite passes in front of or behind the objects 
on the screen. Sprites can be expanded to twice their original size in 
either the horizontal or vertical directions. The type of sprite display 
determines whether the sprite is a standard bit map sprite, or a mul- 
ticolor bit mapped sprite. Here are the two statements that turn on 
sprites 1 and 2. 

60 SPRITE 1,1,7,0,0,0,0:REM TURN ON SPR 1 
65 SPRITE 2,1,3,0,0,0,0:REM TURN ON SPR 2 

Here's what each of the numbers in the SPRITE statements mean; 

SPRITE #,0,C,RX,Y,M 

# — Sprite number (1 through 8) 
O— TumOn(O=1)orOff(O = 0) 
C — Color (1 through 16) 

p _ Priority— If P = 0, sprite is in front of objects on the screen 
If p = 1 , sprite is in back of objects on the screen 
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The MOVSPR command has two alternative forms. See Chapter V, 
BASIC 7.0 Encyclopedia for these notations. 



u 



u 

X — If X = 1 , expands sprite in horizontal (X) direction , , 

If X = 0, sprite is normal horizontal size ! ! 

Y — If Y = 1 , expand sprite in vertical (Y) direction 

If Y = 0, sprite is normal vertical size . 

M— lfM = 1, sprite is multicolor 1 ) 

If M = 0, sprite is standard 

As you can see, the SPRITE statement is powerful, giving you control \ f 
over many sprite qualities. ^ — ' 

Moving Sprites with IMOVSPR LJ 

Now that your sprite is on the screen, all you have to do is move it. 
The MOVSPR statement controls the motion of a sprite and allows j ( 

you to animate it on the screen. The MOVSPR statement can be used ' — ^ 
in two ways. First, the MOVSPR statement can place a sprite at an 
absolute location on the screen, using vertical and horizontal coordi- 
nates. Add the following statements to your program: 

70 MOVSPR 1,240,70:REM POSITION SPRITE 1-X = 240, Y = 70 
80 MOVSPR 2,120,70:REM POSITION SPRITE 2— X = 120, Y = 70 

Line 70 positions sprite 1 at sprite coordinate 240,70. Line 80 places 
sprite 2 at sprite coordinate 1 20,70. You can also use the MOVSPR 
statement to move sprites relative to their original positions. For 
example, place sprites 1 and 2 at the coordinates as in lines 70 and 
80. You want to move them from their original locations to another 
location on the screen. Use the following statements to move sprites 
along a specific route on the screen: 

80 MOVSPR,1,180 # 6:REM MOVE SPRITE 1 FROM THE TOP \\ 

TO THE BOTTOM 

87 MOVSPR 2,180 # 7:REM MOVE SPRITE 2 FROM THE TOP 

TO THE BOTTOM |_j 

The first number in this statement is the sprite number. The second 
number is the direction expressed as the number of degrees to move 
in the clockwise direction, relative to the original position of the 
sprite. The pound sign (#) signifies that the sprite is moved at the 
specified angle and speed relative to a starting position, instead of 
an absolute location, as in lines 70 and 80. The final number speci- 
fies the speed in which the sprite moves along its route on the 
screen, which ranges from through 15. 
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Sprites use an entirely different coordinate plane than bit-nnap coor- 
dinates. The bit-nnap coordinates range from points 0,0 (the top left 
corner) to 319,199 (bottom right corner). The visible sprite coordi- 
nates start at point 24,50 and end at point 344,250. The rest of the 
sprite coordinates are off the screen and are not visible, but the 
sprite still moves according to them. The off-screen locations allow 
sprites to move smoothly onto and off of the screen. Figure 6-7 illus- 
trates the sprite coordinate plane and the visible sprite positions. 
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Figure 6-7. Visible Sprite Coordinates 

Now RUN the entire program with all the steps included. You have 
just written your first sprite program. You have created a raceway 
with two racing cars. Try adding more cars and more objects on the 
screen. Experiment by drawing other sprites and include them in the 
raceway You are now well on the way in sprite programming. Use 
your imagination and think of other scenes and objects you can 
animate. Soon you will be able to create all kinds of animated com- 
puter "movies." 

To stop the sprites, press RUN/STOP and RESTORE at the same 
time. 
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Creating a Sprite Program 

You now have a working sprite program example. Here's tine com- 
plete program listing: 
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5 COLOR 0,1 

10 GRAPHIC 1,1 

15 BOX 1,2,2,45,45 

20 DRAW 1,17,10 TO 28,10 TO 26,30 TO 19,30 TO 17,10 :REM CAR BODY 

22 DRAW 1,11,10 TO 15,10 TO 15,18 TO 11,18 TO 11,10: REM UP LEFT WHEEL 

24 DRAW 1,30,10 TO 34,10 TO 34,18 TO 30,18 TO 30,10:REM RGHT WHEEL 

26 DRAW 1,11,20 TO 15,20 TO 15,28 TO 11,28 TO 11,20:REM LOW LFT WHEEL 

28 draw: 1> 30., 20 TO 34,20 TO 34,28 TO 30,28 TO 30,20:REM LO RGHT WHEEL 

30 DRAW i;26,28 TO 19,28 

32 BOX 1,20,14,26,18,90,1 

35 BOX 1,150,35,195,40,90,1:REM STREET 

37 BOX 1,150, 135, 195, 140, 90, 1:REM STREET 

40 BOX i,150,215,195,220,90,l:REM STRT 

42 BOX 1,50,180,300,194 

44 CHAR 1,18,23, "FINISH" 

45 SSHAPE A$,11,10,34,30:REM SAVE SPR IN A$ 
50 SPRSAV A$,1:REM SPRO DATA 

55 SPRSAV A$,2:REM SPRl DATA 

60 SPRITE 1,1,7,0,0,0,0:REM SPRl ATTRIB 

65 SPRITE 2,1,3,0,0,0,0:REM SPR2 ATTRIB 

70 MOVSPR 1^240,0: REM MOVE SPl TO ABSOLUTE COORD. 240,0 

80 M)t^SPR: 2vf20,0:REM MOVE SP2 TO ABSOLUTE COORD. 120,0 

85 MOVSPR 1,180 # 6: REM MOVE SPl 180 DEGREES RELATIVE TO 240,0 

90 MOVSPR 2,180 # 7: REM MOVE SP2 180 DEGREES RELATIVE TO 120,0 

95 SLEEP 15 :REM DELAY 

99 GRAPHIC 0,1: REM RETURN TO TEXT MODE 



Here's what the program does: 

• Line 5 COLORS the screen black. 

• Line 10 sets standard high-resolution GRAPHIC mode. 

• Line 15 DRAWs a box in the top-left corner of the screen. 

• Lines 20 through 32 DRAW the racing car. 

• Lines 35 through 44 DRAW the racing lanes and a finish line. 

• Line 45 transfers the picture data from the racing car into a 
string variable. 

• Lines 50 and 55 transfer the contents of the string variable 
into sprites 1 and 2. 

• Lines 60 and 65 turn on sprites 1 and 2. 

• Lines 70 and 80 position the sprites at the top of the screen. 

• Lines 85 and 90 animate the sprites as through two cars are 
racing each other across the finish line. 
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In this section, you have learned how to create sprites, using the 
built-in C128 graphics statements such as DRAW and BOX. You 
learned how to control the sprites, using the Comnnodore 128 sprite 
statennents. The Connmodore 128 has two other ways of creating 
sprites. The first is with the built-in SPRite DEFinition ability, as 
described in the following paragraphs. The other nnethod of creating 
sprites is the same as that used for the Commodore 64; see the C64 
Programmer's Reference Guide for details on this sprite-creation 
technique. 



Adjoining Sprites 

You have learned how to create, color, turn on and animate a sprite. 
An occasion may arise when you want to create a picture that is too 
detailed or too large to fit into a single sprite. In this case, you can 
join two or more sprites so the picture is larger and more detailed 
than with a single sprite. By joining sprites, each one can move inde- 
pendently of one another. This gives you much more control over 
animation than a single sprite. 

This section includes an example using two adjoining sprites. Here's 
the general procedure (algorithm) for writing a program with two or 
more adjoining sprites. 

1 . Draw a picture on the screen with Commodore 128 graphics state- 
ments, such as DRAW, BOX and PAINT, just as you did in the race- 
way program in the last section. This time, make the picture twice 
as large as a single sprite with the dimensions 48 pixels wide by 21 
pixels tall. 

2. Use two SSHAPE statements to store the sprites into two sepa- 
rate data strings. Position the first SSHAPE statement coordinates 
over the 24 by 21 pixel area of the first half of the picture you drew. 
Then position the second SSHAPE statement coordinates over 
the second 24 by 21 pixel area. Make sure you store each half of 
the picture data in a different string. For example, the first 
SSHAPE statement stores the first half of the picture into A$, and 
the second SSHAPE statement stores the second half of the pic- 
ture in B$. 

3. Transfer the picture data from each data string into a separate 
sprite with the SPRSAV statement. 

4. Turn on each sprite with the SPRITE statement. 

5. Position the sprites so the beginning of one sprite starts at the 
pixel next to where the first sprite ends. This is the step that actu- 
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ally joins the sprites. For example, draw a picture 48 by 21 pixels. 
Position the first sprite (1 , for example) at location 10,10 with this 
statement: 



Here's the program listing: 
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100 MOVSPR 1,10,10 

where the first number is the sprite number, the second number is 
the horizontal (X) coordinate and the third number is the vertical 
(Y) coordinate. Position the second sprite 24 pixels to the right of 
sprite 1 with this statement: 

200 MOVSPR 2,34,10 [J 

At this point, the two sprites are displayed directly next to each 
other. They look exactly like the picture you drew in the beginning ^ ^ 

of the program, using the DRAW, BOX and PAINT statements. ^ — ^ 

6. Now you can move the sprites any way you like, again using the 
MOVSPR statement. You can move them together along the same 
path or in different directions. As you learned in the last section, 
the MOVSPR statement allows you to move sprites to a specific 
location on the screen, or to a location relative to the sprite's origi- 
nal position. 
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The following program is an example of adjoining sprites, the pro- 
gram creates an outer space environment, it draws stars, a planet 
and a spacecraft similar to Apollo. The spacecraft is drawn, then 
stored into two data strings, A$ and B$. The front of the spaceship, 
the capsule, is stored in sprite 1 . The back half of the spaceship, the 
retro rocket, is stored in sprite 2. The spacecraft flies slowly across 
the screen twice. Since it is traveling so slowly and is very far from , , 

Earth, it needs to be launched earthward with the retro rockets. 1 I 

After the second trip across the screen, the retro rockets fire and 
propel the capsule safely toward Earth. 
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5 COLOR 4,1: COLOR 0,1 .-COLOR 1,2: REM SELECT BLACK BORDER & BKGRND, WHITE FRGRD 
10 GRAPHIC 1,1: REM SET HI RES MODE 

17 FOR I=lTO40 

18 X=INT(RND(1)*320)+1:REM DRAW STARS 

19 Y=INT(RND(1)*200)+1:REM DRAW STARS 

21 DRAW 1,X,Y:NEXT :REM DRAW STARS 

22 BOX 0,0,5,70,40,,1:REM CLEAR BOX 

23 BOX 1,1,5,70,40:REM BOX-IN SPACESHIP 

24 COLOR 1,8:CIRCLE 1 , 190, 90 , 35, 25 rPAINT 1,190,95:REM DRAW & PAINT PLANET 

25 CIRCLE 1,190,90,65,10:CIRCLE 1 , 190, 93, 65, 10 :CIRCLE 1 , 190 , 95, 65, 10 :COLOR 0,1 

26 DRAW 1,10,17 TO 16,17 TO 32,10 TO 33,20 TO 32,30 TO 16,23 TO 10,23 TO 10,17 
28 DRAW 1,19,24 TO 20,21 TO 27,25 TO 26,28 :REM BOTTOM WINDOW 

35 DRAW 1,20,19 TO 20,17 TO 29,13 TO 30,18 TO 28,23 TO 20,19:REM TOP WINDOW 

38 PAINT 1,1 3, 20: REM PAINT SPACESHIP 

40 DRAW 1,34,10 TO 36,20 TO 34,30 TO 45,30 TO 46,20 TO 45,10 TO 34,10:REM SPl 

42 DRAW 1,45,10 TO 51,12 TO 57,10 TO 57,17 TO 51,15 TO 46,17:REM ENGl 

43 DRAW 1,46,22 TO 51,24 TO 57,22 TO 57,29 TO 51,27 TO 45,29:REM ENG2 

44 PAINT 1,40,15:PAINT 1 , 47, 12 :PAINT 1,47,26:DRAW 0,45,30 TO 46,20 TO 45,10 

45 DRAW 0,34,14 TO 44,14 :DRAW 0,34,21 TO 44,21:DRAW 0,34,28 TO 44,28 

47 SSHAPE A$,10,10,33,30:REM SAVE SPRITE IN A$ 

48 SSHAPE B$,34,10,57,30:REM SAVE SPRITE IN B$ 
50 SPRSAV A$,1:REM SPRl DATA 

55 SPRSAV B$,2:REM SPR2 DATA 

60 SPRITE 1,1,3,0,0,0,0:REM SET SPRl ATTRIBUTES 

65 SPRITE 2, 1,7, 0,0, 0,0: REM SET SPR2 ATTRIBUTES 

82 MOVSPR 1,150 ,150:REM ORIGINAL POSITION OF SPRl 

83 MOVSPR 2,172 ,150:REM ORIGINAL POSITION OF SPR2 
85 MOVSPR 1,270 # 5 :REM MOVE SPRl ACROSS SCREEN 
87 MOVSPR 2,270 # 5 :REM MOVE SPR2 ACROSS SCREEN 
90 FOR I=1T0 5950:NEXT:REM DELAY 

92 MOVSPR 1,150,150:REM POSITION SPRl FOR RETRO ROCKET LAUNCH 

93 MOVSPR 2,174, 150 :REM POSITION SPR2 FOR RETRO ROCKET LAUNCH 

95 MOVSPR 1,270 # 10 :REM SPLIT ROCKET 

96 MOVSPR 2,125 # 5 :REM SPLIT ROCKET 

97 FOR I=1T0 1200:NEXT:REM DELAY 

98 SPRITE 2,0:REM TURN OFF RETRO ROCKET (SPR2) 

99 FOR 1=1 TO 20500: NEXT: REM DELAY 

100 GRAPHIC 0,1: REM RETURN TO TEXT MODE 



Here's an explanation of the program: 



Line 5 COLORS the background black and the foreground 
white. 

Line 10 selects standard high-resolution nnode and clears the 
high-res screen. 

Lines 17 through 21 DRAW the stars. 
Line 23 BOXes in a display area for the picture of the space- 
craft in the top-left corner of the screen. 
Line 24 DRAWs and PAINTs the planet. 
Line 25 DRAWs the CIRCLES around the planet. 
Line 26 DRAWs the outline of the capsule portion of the 
spacecraft. 
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Line 28 DRAWS the bottom window of the space capsule. I / 

Line 35 DRAWs the top window of the space capsule. 

Line 38 RAINTs the space capsule white. 

Line 40 DRAWs the outline of the retro rocket portion of the j / 

spacecraft. — ' 

Line 42 and 43 DRAW the retro rocket engines on the back of 

the spacecraft. j 1 

Line 44 RAINTs the retro rocket engines and DRAWs an out- — ' 

line of the back of the retro rocket in the background color. 

Line 45 DRAWs lines on the retro rocket portion of the space- \ i 

craft in the background color. (At this point, you have dis- ' — ' 

played only pictures on the screen. You have not used any 

sprite statements, so your rocketship is not yet a sprite.) \ j 

Line 47 positions the SSHAPE coordinates above the first half ^ — ' 

(24 by 21 pixels), of the capsule of the spacecraft and stores it 

in a data string, A$. j [ 

Line 48 positions the SSHAPE coordinates above the second ' — * 

half (24 by 21 pixels) of the spacecraft and stores it in a data 

string. B$. j j 

Line 50 transfers the data from A$ into sprite 1 . ^ — ' 

• Line 55 transfer the data from B$ into sprite 2. 

' Line 60 turns on sprite 1 and colors it red. j [ 

' Line 65 turns on sprite 2 and colors it blue. ' — ' 

' Line 82 positions sprite 1 at coordinate 150,150. 
' Line 83 positions sprite 2, 24 pixels to the right of the starting 
coordinate of sprite 1. 
» Lines 82 and 83 actually join the two sprites. 

• Lines 85 and 87 moves the joined sprites across the screen. 

• Line 90 delays the program. This time, delay is necessary for 
the sprites to complete three trips across the screen. If you 
leave out the delay the sprites do not have enough time to 
move across the screen. 

► Lines 92 and 93 position the sprites in the center of the 
screen, and prepare the spacecraft to fire the retro rockets. 

' Line 95 propels sprite 1 , the space capsule, forward. The 
number 10 in line 95 specifies the speed in which the sprite 
moves. The speed ranges from 0, which is stop, to 15, which \ I 

is lightning fast. ^ — ^ 

Line 96 moves the expired retro rocket portion of the space- 
craft backwards and off the screen. 
Line 97 is another time delay so the retro rocket, sprite 2, has 
time to move off the screen. 
Line 98 turns off sprite 2, once it is off the screen. 
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• Line 99 is anotlier delay so tine capsule can continue to nnove 
across the screen. 

• Line 100 returns you to text mode. 

Working with adjoining sprites can be nnore interesting than working 
with a single sprite. The nnain points to remennber are: (1) Make sure 
you position the SSHAPE coordinates at the correct locations on the 
screen, so you save the picture data properly; and (2) be certain to 
position the sprite coordinates in the correct location when you are 
joining them with the MOVESPR statement. In this example, you posi- 
tioned sprite 2 at a location 24 pixels to the right of sprite 1 . 

Once you master the technique of adjoining two sprites, try more 
than two. The more sprites you join, the better the detail and anima- 
tion will be in your programs. 

The C128 has two additional SPRITE commands, SPRCOLOR and 
COLLISION, which are not covered in this chapter. To learn about 
these commands, refer to Chapter V, the BASIC 7.0 Encyclopedia. 



Storing Sprite Data in Binary Files 

The Commodore 128 has two new commands, BLOAD and BSAVE, 
which make handling sprite data neat and easy. The "B" in BLOAD 
and BSAVE stand for BINARY. The BSAVE and BLOAD commands 
save and load binary files to and from disk. A binary file consists of 
either a portion of a machine language program, or a collection of 
data within a specified address range. You may be familiar with the 
SAVE Command within the built-in machine language monitor. When 
you use this SAVE command, the resulting file on disk is considered 
a binary file. A binary file is easier to work with than an object code 
file since you can load a binary file without any further preparation. 
An object code file must be loaded with a loader, as in the Commo- 
dore 64 Assembler Development System; then the SYSTEM com- 
mand (SYS) must be used to execute it. 

You're probably wondering what this has to do with sprites. Here's 
the connection. The Commodore 128 has a dedicated portion of 
memory ranging from decimal address 3584 ($0E00) through 4095 
($OFFF), where sprite data is stored. This portion of memory takes 
up 512 bytes. As you know, a sprite is 24 pixels wide by 21 pixels tall. 
Each pixel requires one bit of memory. If the bit in a sprite is off 
(equal to 0), the corresponding pixel on the screen is considered off 
and it takes on the color of the background. If a pixel within a sprite is 
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on (equal to 1), the corresponding pixel on the screen is turned on in 
the foreground color. The connbination of zeroes and ones produces 
the innage you see on the screen. 

Since a sprite is 24 by 21 pixels and each pixel requires one bit of 
storage in memory one sprite uses up 63 bytes of memory See Fig- 
ure 6-8 to understand the storage requirements for a sprite's data. 
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Each Row = 24 bits = 3 bytes | I 

Figure 6-8. Sprite Data Requirements 
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A sprite requires 63 bytes of data. Each sprite block is actually made 

up of 64 bytes; the extra byte is not used. Since the Commodore 128 ^ ) 

has eight sprites and each one consists of a 64-byte sprite block, the 1 1 

computer needs 512 (8 x 64) bytes to represent the data of all eight 
sprite images. 

L! 

1 24 USING 0128 MODE— Color, Animation and Sprite Graphics Statei^ients 

u 



I I 



I I 



n 



The entire area where all eight sprite blocks reside starts at memory 
location 3584 ($0E00) and ends at location 4095 ($OFFF). Figure 6-9 
lists the memory address ranges where each individual sprite stores 
its data. 



f \ 



I \ 



1 i 



I \ 



i I 



; \ 



$OFFF (4095 Decimal) 

]— Sprites 
$OFCO 

]— Sprite? 
$0F80 

]— Sprites 
$0F40 

]— Sprites 
$0F00 

]— Sprite 4 
$OECO 

]— Sprites 
$OESO 

]— Sprite 2 
$0E40 

]— Sprite 1 
$0E00(35S4 Decimal) 

Figure S-9. Memory Address Ranges for Sprite Storage 

BSAVE Once you exit from the SPRDEF mode, you can 

save our sprite data in binary sprite files. This 
way you can load any collection of sprites back 
into the Commodore 128 neatly and easily Use 
this command to save your sprite data into a 
binary file: 

BSAVE "filename", BO, P3584 TO P4096 

The binary filename is a name you give to the file. The "BO" specifies 
that you are saving the sprite data from bank 0. The parameters 
"P3584 TO P4096" signify you are saving the address range 3584 
($0E00) through 4095 ($OFFF), which is the range where all the sprite 
data is stored. 

You do not have to define all of the sprites when you BSAVE them. 
The sprites you do define are BSAVEd from the correct sprite block. 
The undefined sprites are also BSAVEd in the binary file from the 
appropriate sprite block, but they do not matter to the computer. It is 
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easier to BSAVE the entire 512 bytes of all eight sprites, regardless if 
all the sprites are used, rather than BSAVE each sprite block individ- 
ually. 



*•**•••••*••*••*•*••••*•••*••*••*••*•**•*****•••*•**•• 



In this section you have seen how much the new Commodore 7.0 
BASIC commands can simplify the usually complex process of cre- 
ating and animating graphic images. The next section describes 
some other new BASIC 7.0 commands that do the same for music 
and sound. 
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BLOAD Later on, when you want to use the sprites 

again, just BLOAD the entire 512 bytes for all of 
the sprites into the range starting at 3584 I ( 

($0E00) and ending at 4095 ($OFFF). Here's the ^-^ 

connnnand to acconnplish this: 

BLOAD "filename"[, BO, P3584] Li 

Use the sanne filename you entered when you BSAVEd your original 
sprite data. The "BO" stands for the bank number and the P3584 1 | 

specifies the starting location where the binary sprite data file is 
loaded. The last two parameters are optional. 
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NOTE: When you BLOAD sprite data into the sprite storage area, all 
the data that was previously there is overwritten with the 
binary sprite data file. If you used SPRite DEFinition mode to ^i J 
create sprites, BSAVE them before you BLOAD new data, or ^ — 

your original data will be lost. 
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The Commodore 128 has one of the most sophisticated built-in 
sound synthesizers available in a microcomputer. The synthesizer, 
called the Sound Interface Device (SID), is a chip dedicated solely to 
generating sound and music. The SID chip is capable of producing 
three independent voices (sounds) simultaneously Each of the 
voices can be played in one of four types of sounds, called wave- 
forms. The SID chip also has programmable Attack, Decay Sustain 
and Release (ADSR) parameters. These parameters define the qual- 
ity of a sound. In addition, the synthesizer has a filter you can use to 
choose certain sounds, eliminate others, or modify the characteris- 
tics of a sound or sounds. In this section you will learn how to control 
these parameters to produce almost any kind of sound. 

To make it easy for you to select and manipulate the many capabili- 
ties of the SID chip. Commodore has developed new and powerful 
BASIC music statements. 

Here are the new sound and music statements available on the 
Commodore 128: 

SOUND 

ENVELOPE 

VOL 

TEMPO 

PLAY 

FILTER 

This section explains these sound statements, one at a time, in the 
process of constructing a sample musical program. When you are 
finished with this section, you will know the ingredients that go into a 
musical program. You'll be able to expand on the example and write 
programs that play intricate musical compositions. Eventually you'll 
be able to program your own musical scores, make your own sound 
effects and play works of the great classical masters such as 
Beethoven and contemporary artists like the Beatles. You can even 
add computer-generated music to your graphics programs to create 
your own "videos." 
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The SOUND 
Statement 



The SOUND statement is designed prinnarily for quick and easy 
sound effects in your progranns. You will learn a nnore intricate way of 
playing complete musical arrangements with the other sound state- 
ments later in this section. 



The format for the SOUND statement is as follows: 

SOUND VC, FREQ, DUR[, DIR[, MIN[, SV[, WF[, PW]]]]] 

Here's what the parameters mean: 
VC — SelectVoiCe1,2or3 

FREQ— Set the FREQuency level of sound (0-65535) 

DUR —Set DURation of the sound (in 60ths of a second) 
(0-32767) 

DIR — Set the DIRection in which the sound is incremented/ 
decremented 

= Increment the frequency upward 

1 = Decrement the frequency downward 

2 = Oscillate the frequency up and down 

MIN —Select the MINimum frequency (0-65535) if the 
sweep (DIR) is specified 

SV —Choose the Step Value for the sweep (0-32767) 

WF —Select the Wave Form (0-3) 

= Triangle 

1 = Sawtooth 

2 = Variable Pulse 

3 = White Noise 

PW —Set the Pulse Width, the width of the variable pulse 
waveform 



u 
u 

u 



u 



u 
u 
u 
u 
u 
u 
u 



Note that the DIR, MIN, SV, WF and PW parameters are optional. 
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The first parameter (VC) in the SOUND statement selects which 
voice will be played. The second parameter (FREQ) determines the 
frequency of the sound, which ranges from through 65535. The 
third setting (DUR) specifies the amount of time the sound is played. 
The duration is measured in 60ths of a second. If you want to play a 
sound for one second, set the duration to 60, since 60 times 1/60 
equals 1 . To play the sound for two seconds, specify the duration to 
be 1 20. To play the sound 1 seconds, make the duration 600, and so 
on. 



I \ 



n 



The fourth parameter (DIP) selects the direction in which the fre- 
quency of the sound is incremented or decremented. This is referred 
to as the sweep. The fifth setting (MIN) sets the minimum frequency 
where the sweep begins. The sixth setting (SV) is the step value of 
the sweep. It is similar to the step value in a FOR . . . NEXT loop. If 
the DIP, MIN and SV values are specified in the SOUND command, 
the sound is played first at the original level specified by the FPEQ 
parameter. Then the synthesizer sweeps through and plays each 
level of the entire range of frequency values starting at the MIN fre- 
quency The sweep is incremented or decremented by the step value 
(SV) according to the direction specified by the DIP parameter and 
the frequency is played at the new level. 



1 i 
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The seventh parameter (WF) in the SOUND command selects the 
waveform for the sound. (Waveforms are explained in detail in the 
paragraph titled. Advanced Sound and Music in C128 IMode.) 



n 



The final setting (PW) in the SOUND command determines the width 
of the pulse width waveform if it is selected as the waveform param- 
eter. (See the Advanced Sound discussion for an illustration of the 
pulse width waveform.) 



/ \ 
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Writing a SOUND Program 

Now it's time to write your first SOUND program. Here's an example — ' 

of the SOUND statement: 

10 VOL 5 U 

20 SOUND 1, 4096, 60 



RUN tliis program. The Commodore 128 plays a short, high-pitched 
beep. You must set the volume before you can play the sound state- 
ment, so line 10 sets the VOLume of the sound chip. Line 20 plays 
voice 1 at a frequency of 4096 for a duration of 1 second (60 times 1/ 
60). Change the frequency with this statement: 



30 SOUND 1, 8192, 60 



Notice line 30 plays a higher tone than line 20. This shows the direct 
relationship between the frequency setting and the actual frequency 
of the sound. As you increase the frequency setting, the Commodore 
1 28 increases the pitch of the tone. Now try this statement: 



This shows that a FREQ value of plays the lowest frequency (which 
is so low it is inaudable). A FREQ value of 65535 plays the highest 
possible frequency 
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40 SOUND 1, 0, 60 [J 



U 

u 



Now try placing the sound statement within a FOR . . . NEXT loop. ] j 

This allows you to play the complete range of frequencies within the 
loop. Add these statements to your program: 

50 FOR I = 1 TO 65535 STEP 100 LI 

60 SOUND 1, 1, 1 

70 NEXT X j 

u 
u 



u 



n 
n 



This program segment plays the variable pulse waveform in the 
range of frequencies from 1 through 65535, in increments of 100, 
from lowest frequency to highest. If you don't specify the waveform, 
the computer selects the default value of waveform 2, the variable 
pulse waveform. 



Now change the waveform with the following program line (60) and 
try the program again: 



60 SOUND 1, 1, 1, 0, 0, 0, 0, 



/ i 



n 

n 
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Now the program plays voice 1 , using the triangle waveform, for the 
range of frequencies between 1 and 65535 in increments of 100. 
This sounds like a typical sound effect in popular arcade games. Try 
waveform 1 , the sawtooth waveform, and see how it sounds with 
this line: 

60SOUND1J, 1,0,0,0, 1,0 



The sawtooth waveform sounds similar to the triangle waveform 
though it has less buzz. Finally try the white noise waveform (3). 
Substitute line 60 for this line: 



60SOUND1,1, 1,0,0,0, 3,0 



Now the program loop plays the white noise generator for the entire 
range of frequencies. At first, there is a low-pitched rumbling sound. 
As the frequency increases in the loop, the pitch increases and 
sounds like a rocket taking off. 
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Notice that so far, we have not specified all of the parameters in the 
SOUND statement. Take line 60. for example: 

60 SOUND 1,1, 1,0,0,0,3,0 

The three zeros following 1,1,1 pertain to the sweep parameters 
within the SOUND statement. Since none of the parameters is speci- 
fied, the SOUND does not sweep. Add this line to your program: 

100 SOUND 1, 491 52, 240, 1, 0, 100, 1, 

4 A A A 4 44 



Voice . 



Frequency . 
Duration 



Sweep Direction 

Minimum Sweep Frequency . 

Step Value for Sweep 

Waveform 



Pulse Width for Variable Width 
Waveform 



Line 1 00 starts the sweep frequency at 491 52 and decrements the 
sweep by 100 in the downward direction, until it reaches the mini- 
mum sweep frequency at 0. Voice 1 , using the sawtooth waveform 
(#1), plays each SOUND for four seconds (240 * 1/60 sec). Line 100 
sounds like a bomb dropping, as in many "shoot 'em up" arcade 
games. 

Now try changing some of the parameters in line 1 00. For instance, 
change the direction of the sweep to 2 (oscillate); change the mini- 
mum frequency of the sweep to 32768; and increase the step value 
to 3000. Your new SOUND command looks like this: 

110 SOUND 1, 49152, 240, 2, 32768, 3000, 1 

Line 1 1 makes a siren sound as though the police were right on 
your tail. For a more pleasant sound, try this: 

110 SOUND 1, 65535, 250, 0, 32768, 3000, 2, 2600 

This should remind you of a popular space-age TV show, when the 
space crew unleashed their futuristic weapons on the unsuspecting 
aliens. 

Until now, you have been programming in only one voice. You can 
produce interesting sound effects with the SOUND statement using 



u 
u 



u 
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up to three voices. Experiment and create a progrann which utilizes 
all three voices. 



Here's a sannple progrann that will help you understand how to pro- 
gram the Commodore 128 synthesizer chip. The program, when run, 
asks for each parameter, and then plays the sound. Here's the pro- 
gram listing. Type it into your computer and RUN it. 



/ \ 
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PRINT:PRINT:PRINT:PRINT"n| SOUND PLAYER" :PRINT:PRINT:PRINT 

PRINT" INPUT SOUND PARAMETERS TO PLAY" : PRINT : PRINT 

INPUT "VOICE (1-3)";V 

INPUT "FREQUENCY (0~65535)"?F 

INPUJ" "DURATION ( 0-32767 )" ;D:PRINT 

I;NPUT"WANT TO SPECIFY OPTIONAL PARAMETERS Y/N" ; B$ : PRINT 

IF &$="N" THEN 130 

INPUT "SWEEP DIRECTION 0=UP, 1=D0WN, 2=0SCILL" ;DIR 

INPUT "MINIMUM SWEEP FREQUENCY (0-65535)" ;M 
) INPUT "SWEEP STEP VALUE (0-32767) ";S 
) Input "WAVEFORM ( 0=TRI , 1=SAW, 2=VAR PUL, 3=N0ISE" ; W 
3 IF W=2 THEN INPUT "PULSE WIDTH ( 0-4095) ";P 
). SOUND V, F, D, DIR, M, S, W, P 

3 INPUT"DO YOU WANT TO HEAR THE SOUND AGAIN Y/N";A$ 
3 IF A$="Y"THEN 130 
3 GOTO 10 



/ 1 



Here's a quick explanation of the program. Lines 1 and 20 PRINT 
the introductory messages on the screen. Lines 30 through 50 
INPUT the voice, frequency and duration parameters. Line 60 asks if 
you want to enter the optional SOUND parameters, such as the 
sweep settings and waveform. If you don't want to specify these 
parameters, press the "N" key and the program jumps to line 1 30 
and plays the sound. If you do want to specify the optional SOUND 
settings, press the "Y" key and the program continues with line 80. 
Lines 80 through 1 1 specify the sweep direction, minimum sweep 
frequency sweep step value and waveform. Line 120 INPUTS the 
pulse width of the variable pulse waveform only if waveform 2 (varia- 
ble pulse) is selected. Finally line 130 plays the SOUND according to 
the parameters that you specified earlier in the program. 

Line 140 asks if you want to hear the SOUND again. If you do, press 
the "Y" key; otherwise, press the "N" key Line 150 checks to see if 
you pressed the "Y" key If you did, program control is returned to 
line 1 30 and the program plays the SOUND again. If you do not press 



135 



USING 0128 MODE— Sound and Music in C128 Mode 



the "Y" key, the program continues with line 160, which returns pro- 
gram control to line 1 and the program repeats. To stop the Sound 
Player program, press the RUN/STOP and RESTORE keys at the 
same time. 

Random Sounds 

The following program generates random sounds using the RND 
function. Each SOUND parameter is calculated randomly Type the 
program into your computer, SAVE it and RUN it. This program illus- 
trates how many thousands of sounds you can produce by specify- 
ing various combinations of the SOUND parameters. Here's the 
listing: 



) I 



10 PRINT" VC FREQ DIE MIN SV WF 


PW " 


20 PRINT" 




30 V=INT(RND(1)*3)+1:REM VOICE 




40 F=INT(RND(1)*65535) : REM FREQ 




50 D=INT(RND(1)*32767) : REM DURATION 




6 DIR=INT(RND(1)*3) :REM STEP DIR 




70 M=INT(RND(1)*65535) :REM MIN FREQ 




80 S=iNT(RND(l)*32767) : REM STEP VAL 




90 W=INT(RND(1)*4) :REM WAVEFORM 




100 P=INT(RND{1)*409 5) :REM PULSE W 




110 PRINTV; F;DIR;M;S;W;P: PRINT: PRINT 




120 SOUND V, F, D, DIR, M, S, W, P • 




130 SLEEP 4 




140 SOUND V, 0, 0, DIR, 0, 0, W, P 




150 GOTOIO 





Lines 10 and 20 PRINT parameter column headings and the under- 
line. Lines 30 through lOOcalculateeach SOUND parameter within 
its specific range. For example, line 30 calculates the voice number 
as follows: 

30 V = INT(RND(1)*3) + 1 

The notation RND (1) specifies the seed value of the random num- 
ber. The seed is the base number generated by the computer. The 1 
tells the computer to generate a new seed each time the command 
is encountered. Since the Commodore 1 28 has three voices, the 
notation * 3 tells the computer to generate a random number within 
the range through 3. Notice, however, there is no voice 0, so the 
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H- 1 in line 30 tells the connputer to generate a randonn number in the 
range between 1 and 3. The procedure for generating a random 
number in a specific range is to multiply the given random number 
times the maximum value of the parameter (in this case, 3). If the 
minimum value of the parameter is greater than zero, add to the ran- 
dom number a value that will specify the minimum value of the range 
of numbers you want to generate (in this case, 1). For instance, line 
40 generates a random number in the range between and 65535. 
Since the minimum value is zero in this case, you do not need to add 
a value to the generated random number. 

Line 110 PRINTS the values of the parameters. Line 120 plays the 
SOUND specified by the random numbers generated in lines 30 
through 1 00. Line 1 30 delays the program for 4 seconds while the 
sound is playing. Line 140 turns off the SOUND after the 4 second 
delay All sounds generated by this program play for the same 
amount of time, since they are all turned off after 4 seconds with line 
1 40. Finally line 1 50 returns control to line 1 0, and the process is 
repeated until you press the RUN/STOP and RESTORE keys at the 
same time. 

So far you have experimented with sample programs using only the 
SOUND statement. Although you can use the SOUND statement to 
play musical scores, it is best suited for quick and easy sound 
effects. The Commodore 128 has other statements designed specifi- 
cally for song playing. The following paragraphs describe the 
advanced sound and music statements that enable you to play com- 
plex musical scores and arrangements with your Commodore 128 
synthesizer. 
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Advanced Sound 
and Music in 
CI 28 Mode 



A Brief Baclcground: Tlie Ciiaracteristics of Sound 

Every sound you hear is actually a sound wave traveling through the 
air. Like any wave, a sound (sine) wave can be represented graphi- 
cally and nnathematically (see Figure 7-1). 




Figure 7-1. Sine Wave 

The sound wave nnoves (oscillates) at a particular rate (frequency) 
which determines the overall pitch (the highness or lowness of the 
sound). 

The sound is also nnade up of harmonics, which are accompanying 
multiples of the overall frequency of the sound or note. The combina- 
tion of these harmonic sound waves give the note its qualities, called 
timbre. Figure 7-2 shows the relationship of basic sound frequencies 
and harmonics. 

.RESULTANT WAVE 

' FUNDAMENTAL (1ST HARMONIC) 
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2ND HARMONIC 3RD HARMONIC 

Figure 7-2. Frequency and Harmonics 

The timbre of a musical tone, (i.e., the way a tone sounds,) is deter- 
mined by the tone's waveform. The Commodore 1 28 can generate 
four types of waveforms: triangle, sawtooth, variable pulse and 
noise. See Figure 7-3 for a graphic representation of these four 
waveforms. 



USING C128 MODE—Sound and Music in C128 Mode 



u 
u 
u 
u 






u 
u 
u 
u 
u 
u 



u 
u 

M 

u 
u 



n 



n 



/ \ 



n 
n 
n 
n 
n 
n 
n 
n 




TRIANGLE 




SAWTOOTH 



-PULSE WIDTH—* 



VARIABLE 
PULSE 




NOISE 



Figure 7-3. Sound Waveforms Types 
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Making Music on the Commodore 1 28 



SUSTAIN LEVEL • 



Figure 7-4. ADSR Phases 
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The ENVELOPE The volume of a sound changes throughout the 
Statement duration of the note, f ronn when you first hear it [_J 

until it is no longer audible. These volume quali- 
ties are referred to as Attack, Decay, Sustain 

and Release (ADSR). Attack is the rate at which j [ 

a musical note reaches its peak volume. Decay 
is the rate at which a musical note decreases 

from its peak volume to its midranged (sustain) \ ( 

level. Sustain is the level at which a musical 
note is played at its midranged volume. Reiease 
is the rate at which a musical note decreases M 

from its sustain level to zero volume. The ENVE- 
LOPE generator controls the ADSR parameters 
of sound. See Figure 7-4 for a graphical repre- j) 

sentation of ADSR. The Commodore 1 28 can 
change each ADSR parameter to 1 6 different 
rates. This gives you absolute flexibility over the j | 

ENVELOPE generator and the resulting proper- 
ties of the volume when the sound is originated. 

u 

/ ' \ 

u 
u 
u 
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One of the most powerful Commodore 128 
sound statements — the one that controls the 
ADSR and waveform— is the ENVELOPE state- 
ment. The ENVELOPE statement sets the differ- 
ent controls in the synthesizer chip which 
makes each sound unique. The ENVELOPE M 

gives you the power to manipulate the SI D syn- 
thesizer. With ENVELOPE, you can select partic- 
ular ADSR settings and choose a waveform for ) j 
your own music and sound effects. The format 
for the ENVELOPE statement is as follows: 

ENVELOPE e[,a[,d[,s[,rI,wl[,Pwllllll LJ 
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Here's what the letters mean: 

e — envelope number (0-9) 

a —attack rate (0-1 5) 

d — decay rate (0-1 5) 

s — sustain level (0-1 5) 

r — release rate (0-1 5) 

wf — waveform — = triangle 

1 = sawtooth 

2 = pulse (square) 

3 = noise 

4 = ring modulation 
pw — pulse width (0-4095) 

Here are the definitions of the parameters not 
previously defined: 

Envelope -The properties of a musical 
note specified by the wave- 
form and the attack, decay 
sustain and release settings 
of the note. For example, the 
envelope for a guitar note 
has a different ADSR and 
waveform than a flute. 

Waveform -The type of sound wave 

created by the combination 
of accompanying musical 
harmonics of a tone. The 
accompanying harmonic 
sound waves are multiples 
of, and are based on the 
overall frequency of the 
tone. The qualities of the 
tone generated by each 
waveform are recognizably 
different from one another 
and are represented graphi- 
cally in Figure 7-3. 

Pulse Width -The length of time between 
notes, generated by the 
pulse waveform. 

Now you can realize the power of the ENVE- 
LOPE statement. It controls most of the musical 
qualities of the notes being played by the sound 
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synthesizer. The Commodore 128 has 10 prede- 
fined envelopes for 1 different musical instru- j | 

ments. In using the predefined envelopes you 
do not have to specify the ADSR parameters, 

waveform and pulse width settings — this is j | 

already done for you. All you have to do is spec- 
ify the envelope number. The rest of the parame- 
ters are chosen automatically by the Commo- | I 

dore 128. Here are the preselected envelopes 
for different types of musical instruments: 



u 



Envelope 










Wave- 




Number Instrument 


Attack 


Decay 


Sustain 


Release 


form 


Width 


Piano 





9 








2 


1536 


1 Accordion 


12 





12 





1 




2 Calliope 








25 










3 Drum 





5 


5 





3 




4 Flute 


9 


4 


4 










5 Guitar 





9 


2 


1 


1 




6 Harpsichord 





9 








2 


512 


7 Organ 





9 


9 





2 


2048 


8 Trumpet 


8 


9 


4 


1 


2 


512 


9 Xylophone 





9 














Figure 7-5. Default Parameters for ENVELOPE Statement 



10 ENVELOPE 0, 5, 9, 2, 2, 2, 1700 
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Now that you have a little background on the 
ENVELOPE statement, begin another example , 

by entering this statement into your Commodore LJ 
128. 



u 



This ENVELOPE statement redefines the default 
piano envelope (0) to the foilowing: Attacl< = 5, U 

Decay = 9, Sustain = 2, Release = 2, wave- 
form remains the same (2) and the pulse width 

of the variable pulse waveform is now 1 700. The | \ 

piano envelope will not take on these properties 

until it is selected by a PLAY statement, which 

you will learn later in this section. j j 
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The next step in progrannming nnusic is setting 
the volume of the sound chip as follows: 

20 VOL 8 

The VOL statennent sets the volunne of the sound 
chip between and 15, where 15 is the nnaxi- 
nnum and is off (no volume). 

The TEMPO The next step in Commodore 1 28 music pro- 

Statement gramming is controlling the tempo, or speed of 

your tune. The TEMPO statement does this for 

you. Here's the format: 

TEMPO n 

where n is a digit between 1 and 255 (and 255 
is the fastest tempo). If you do not specify the 
TEMPO statement in your program, the Com- 
modore 1 28 automatically sets the tempo to 8. 
Add this statement to your musical example 
program: 

30 TEMPO 10 



The PLAY Now it's time to learn how to play the notes in 

Statement your song. You already know how the PRINT 

statement works. You play the notes in your tune 
the same way as PRINTing a text string to the 
screen, except you use the PLAY statement in 
place of PRINT PRINT outputs text, PLAY out- 
puts musical notes. 

Here's the general format for the play statement: 

PLAY"string of synthesizer control 
characters and musical notes" 

The total number of characters (including musi- 
cal notes and synthesizer control characters) 
that can be put into a PLAY command is 255. 
However, since this exceeds the maximum 
number of characters (1 60) allowed for a single 
program line in BASIC 7.0, you have to concate- 
nate (that is, add together) at least two strings to 
reach this length. You can avoid the need to 
concatenate strings by making sure your PLAY 
commands do not exceed 160 characters, i.e., 
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one program line in lengtii. (This is equivalent to , 

four screen lines in 40-colunnn nnode, and two 1 1 

screen lines in 80-column nnode.) By doing this, 

you will produce PLAY connmand strings that ^ , 

are easier to understand and use. I I 

To play nnusical notes, enclose the letter of the . ■ 

note you want to play within quotes. For exann- I [ 

pie, here's how to play the musical scale: 

40 PLAY "C D E F G A B" \ / 

This plays the notes C, D, E, F, G, A and B in the 

piano envelope, which is envelope 0. After each ^ , 

time you RUN this example program you are 1 1 

creating, hold down the RUN/STOP key and 

press the RESTORE key to reset the synthesizer , 

chip. LJ 

You have the option of specifying the duration of ^ 

the note by preceding it in quotes with one of | j 

the following letters: 

W-Whole note 
H -Half note 
Q -Quarter note 
I -Eighth note 
S -Sixteenth note 

The default setting, if the duration is not speci- 
fied, is for Whole (W) notes. 

You can PLAY a rest by including the following in 
the PLAY string: 

R-Rest 

You can instruct the computer to wait until all 
voices currently playing reach the end of a mea- 
sure by including the following in quotes: 

M-Wait for end of nneasure 

The Commodore 128 also has synthesizer con- 
trol characters you can enclose within quotes in 
a PLAY string. This gives you absolute control 
over each note and allows you to change syn- 
thesizer controls within a string of notes. Follow 
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the control character with a number in the allow- 
able range for that character. The control char- 
acters and the range of numbers for each are 
shown in Figure 7-6. The "n" following the con- 
trol character refers to the number you select 
from the specified range. 



Control 






Default 


Character 


Description 


Range 


Setting 


Vn 


Voice 


1-3 


1 


On 


Octave 


0-6 


4 


Tn 


Envelope 


0-9 





Un 


Volume 


0-15 


9 


Xn 


Filter 


O = off, 
1=on 





Figure 7-6. Sound Synthesizer 






Control Characters 





Although the SID chip can process these con- 
trol characters in any order, for the best results, 
place the control characters in your string in the 
order that they appear in Figure 7-6. 

You don't absolutely have to specify any of the 
control characters, but you should to maximize 
the power from your synthesizer. The Commo- 
dore 128 automatically sets the synthesizer 
controls to the default settings in Figure 7-6. If 
you don't assign special control characters, the 
SID chip can PLAY only one envelope, one voice 
and one octave without any FILTERing. Specify 
the control characters to exercise the most con- 
trol over the notes within your PLAY string. 

If you specify an ENVELOPE statement and 
select your own settings instead of using the 
default parameters from Figure 7-5, the enve- 
lope control character number in your PLAY 
string must match the envelope number in your 
ENVELOPE statement in order to assume the 
parameters you assigned. You don't have to 
specify the ENVELOPE statement at all if you 
just want to PLAY the default envelope settings 
from Figure 7-6. In this case, simply select an 
envelope number with the (T) control character 
in the PLAY statement. 
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Here's an example of the PLAY statement using 
the SID chip control characters within a string. 
Add this line to your program and notice the 
difference between this statement and the 
PLAY statement in line 40. 

50 PLAY "V2 05 T7 U5 XO C D E F G A B" 



60 PLAY "V3 06 T6 U7 XO C D E F G A B" 
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This statement PLAYS the same notes as in line 
40, but voice 2 is selected, the notes are played 

one octave higher (5) than line 40, the volume { { 

setting is turned down to 5 and the FILTER is 

specified as off. For now, leave the filter off. 

When you learn about FILTERing in the next M 

section, you can come back and turn the filter 

on to see how it affects the notes being played. 

Notice line 50 selects a new instrument, the j j 

organ envelope, with theT7 control character. 
Now your program PLAYS two different instru- 
ments in two of the independent voices. Add j j 
this statement to PLAY the third voice: 



u 



Here's how line 60 controls the synthesizer. The 
V3 selects the third voice, 06 places voice 3 one 
octave higher (6) than voice two, T6 selects the jj 
harpsichord envelope, U7 sets the volume to 7 
and XO leaves the filter off for all three voices. 
Now your program PLAYS all three voices, each I [ 
one octave higher than the other, in three sepa- 
rate instruments, piano, organ and harpsichord. 

So far, your PLAY statements only played whole — 
notes. Add notes of different duration by placing 

duration control characters in your PLAY string j j 

as follows: ^ 

70 PLAY "V2 06 TO U7 XO H C D Q E F I G . 

A S B" Li 

Line 70 PLAYs voice 2 in octave 6 at volume 

level 7 with the redefined piano envelope (0) on j | 

and filter turned off. This statement PLAYs the — ' 

notes C and D as half notes, E and F as quarter 

notes, G and A as eighth notes and B as a six- j | 

teenth note. Notice the difference between the ^-^ 
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The SID Filter 



piano envelope in line 40 and the redefined 
piano envelope in line 70. Line 40 actually 
sounds more like a piano than line 70. 

You can PLAY sharp, flat and dotted notes by 
preceding the notes within quotes with the fol- 
lowing characters: 

#- Sharp 

$-Flat 

.-Dotted 

A dotted note plays one-and-a-half tinnes longer 
than a note that is not dotted. 

Now try adding sharp, flat and dotted notes with 
this statement: 

80 PLAY "V1 04 T4 U8 XO -H C D Q # E F I 
$ G A .S # B" 

Line 80 PLAYS voice 1 in octave 4 at volume 
level 8 with the flute envelope turned on and the 
filter turned off. It also PLAYS C and D as dotted 
half notes, E and F as sharp quarter notes, G 
and A as flat eighth notes and B as a sharp dot- 
ted sixteenth note. You can add rests (R) at any 
place within your PLAY string. The spaces in the 
new PLAY statement examples are not neces- 
sary They are used only for readability 

Up until now your statement examples have left 
the filter off within the sound synthesizer and 
have not realized the true power behind it. Now 
that you have digested most of the sound and 
music statements and the SID control charac- 
ters, move on to the next section to learn how to 
enhance your musical quality with the FILTER 
statement. 

Once you have selected the ENVELOPE, ADSR, 
VOLume and TEMPO, use the FILTER to perfect 
your synthesized sounds. In your program, the 
FILTER statement will precede the PLAY state- 
ment. First you should become comfortable 
with generating the sound and worry about FIL- 
TERing last. Since the SID chip has only one 
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filter, it applies to all three voices. Your comput- I | 
erized tunes will play without FILTERing, but to 
take full advantage of your music synthesizer, 

use the FILTER statennent to increase the sharp- 1 [ 

ness and quality of the sound. ' — 

In the first paragraph of this section, The Char- I j 
acteristics of Sound, we defined a sound as a * — ' 
wave traveling (oscillating) through the air at a 
particular rate. The rate at which a sound wave \ ( 
oscillates is called the wave's frequency Recall "" — ' 
that a sound wave is nnade up of an overall fre- 
quency and acconnpanying harnnonics, which i j 
are multiples of the overall frequency See Fig- ' — ^ 
ure 7-2. The accompanying harmonics give the 
sound its timbre, the qualities of the sound i | 
which are determined by the waveform. The ' — ' 
filter within the SID chip gives you the ability to 
accent and eliminate the harmonics of a wave- 
form and change its timbre. 



u 
u 

u 



The SID chip filters sounds in three ways: low- 
pass, band-pass and high-pass filtering. These 
filtering methods are additive, meaning you can 
use more than one filter at a time. This is dis- 
cussed in the next section. Low-pass filters out 
frequencies above a certain level you specify 
called the cutoff frequency The cutoff f re- i j 

quency is the dividing line that marks the bound- ' — ' 
ary of which frequency level will be played and 
which will not. In low-pass filtering, the SID chip 
plays all frequencies below the cutoff frequency 
and filters out the frequencies above it. As the 
name implies, the low frequencies are allowed i { 

to pass through the filter and the high ones are ' — ' 
not. The low-pass filter produces full, solid 
sounds. See Figure 7-7. 
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FREQUENCY 

Figure 7-7. Low-pass Filter 

Conversely, the high-pass filter allows all the 
frequencies above the cutoff frequency to pass 
through the chip. All the ones below it are fil- 
tered out. See Figure 7-8. The pass filter pro- 
duces tinny hollow sounds. 
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Figure 7-8. High-pass Filter 

The band-pass filter allows a range of frequen- 
cies partially above and below the cutoff fre- 
quency to pass through the SID chip. All other 
frequencies above and below the band sur- 
rounding the cutoff frequency are filtered out. 
See Figure 7-9. 
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Figure 7-9. Band-pass Filter 
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The FILTER The FILTER statement specifies tine cutoff f re- 

Statement quency, tine type of filter being used and the 

resonance. The resonance is the peaking effect 
of the sound wave frequency as it approaches 
the cutoff frequency The resonance determines 
the sharpness and clearness of a sound: the 
higher the resonance, the sharper the sound. 

This is the format of the FILTER statement: 
FILTER cf, Ip, bp, hp, res 

Here's what the parameters mean: 



u 



cf -Cutoff frequency (0-2047) , i 

Ip -Low-pass filter = off, 1 = on 1 I 

bp -Band-pass filter = off, 1 = on 

hp -High-pass filter = off, 1 = on , | 

res -Resonance (0-1 5) i I 



You can specify the cutoff frequency to be any | 1 

value between and 2047. Turn on the low-pass 
filter by specifying a 1 as the second parameter 

in the FILTER statement. Turn on the band-pass I | 

filter by specifying a 1 as the third parameter 
and enable the high-pass filter with a 1 in the 

fourth parameter position. Turn off any of the 1 | 

three filters by placing a in the respective posi- 
tion of the filter you want to disable. You can .. , 
enable or disable one, two or all three of the lJ 
filters at the same time. 

Now that you have some background on the | | 

FILTER statement, add this line to your sound 
program, but do not RUN the program yet. 

45 FILTER 1200, 1, 0, 0, 10 

Line 45 sets the cutoff frequency at 1 200, turns 
on the low-pass filter, disables the high-pass and [_| 
band-pass filters and assigns a 1 as the reso- 
nance level. Now go back and turn the filter on 

in your PLAY statements by changing all the XO 1 \ 

filter control characters to X1 . Reset the sound 
chip by pressing the RUN/STOP and RESTORE 

keys and RUN your sound program again. j j 

Notice the differences between the way the 
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notes sound and how they sounded without the 
filter. Change line 45 to: 

45 FILTER 1200, 0, 1, 0, 10 

The new line 45 turns off the low-pass filter and 
enables the band-pass filter. Press RUN/STOP 
and RESTORE and RUN your sound program 
again. Notice the difference between the low- 
pass and band-pass filters. Change line 45 again 
to: 

45 FILTER 1200, 0, 0, 1, 10 

Reset the sound chip and RUN your example 
program again. Notice the difference between 
the high-pass filter and the low-pass and band- 
pass filters. Experiment with different cutoff 
frequencies, resonance levels and filters to per- 
fect the music and sound in your own programs. 



lying Your Music Program Togetlier 

Your first musical program is complete. Now you can program your 
favorite songs. Let's tie all the components together. Here's the pro- 
gram listing. Don't be alarmed, this is the same program you built in 
this section except the print statements are added so you know 
which program lines are being played. 









•^>i^'}t^\'' 'l ~} 



10 ENVELOPE 0,5,:9,:2',2,2,1700 

15 VOL 8 - 

20 TEMPO 10 - -Ir. ^ . ^Izi 

25 PRINT"LINE 30".: 

30 PLAY "C D E F G:,A B M" ' 

35 FILTER 12,00 , 0,>0;^>i,, 10 

40 PRINT" LINE 45 "' 
:.45'PLAY'?V2 05 T7 

50 PRINT"§AME AS LINE 45 - FILTER ON" "*- " 

55 PLAy"V2 05 T7 U"5 Xl C D E F G A B M" . 

60 PRINT"LINE 65 -FILTER OFF" 

-65 PLAY„2"V3 06-U7 T6 XOC O-E F. G, A a M'V v^fe' 

i7o PRiiwr'^^ME m::^im' 65' ^i^tthEFi^^mf'^t-' > ^'-'^H^ 

75 PLAY "V3 06 U7 T6 XI C D E F G A B M" 
80 PRINT"LINE 8.5 - FILTER OFF" 

85 PLAY "V2 06 TO U7 XO H CD Q EF I GA S B M"^ 
90 PRINT"SAME AS:€.-tNE 85 -,Fi-LTER: ON" :*;:;'. . ..' "-/i 
95 PLAYcAlV-2 06;Tb^;;tf7;"xl H. CD^Q EF I GA SlB M'"/l? 
100 PRINT" iilNE' 105 - FILTER OFF" ' : : 
105 PLAY "VI 04 :T4 U8 XO 'H /C D Q # EF I $ GA S 
110 PRINT"SAME AS LINE 105 - FILTER ON" 
.115 PLAY ,"V1 04 T4- US. Xl H -.jG-D Q # EF.J $ GA S. 



M" 
M:" 
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Line 10, the ENVELOPE statement, specifies tine envelope for piano 
(0), whicli sets the attack to 5, decay to 9, sustain to 2 and release to 
0. It also selects the variable pulse waveform with a pulse width of 
1 700. Line 1 5 sets the VOLume to 8. Line 20 chooses the TEMPO to 
be 10. 



u 
u 
u 



Line 35 FILTERS the notes that are played in lines 30 through 1 1 5. It , | 

sets the FILTER cutoff frequency to 1 200. In addition, line 35 turns ! I 

off the low-pass and band-pass filters with the two zeros following 

the cutoff frequency (1 200). The high-pass filter is turned on with the i . 

1 following the two zeros. The resonance is set to 1 by the last ! i 

parameter in the FILTER statement. 

Line 30 PLAYS the notes 0, D, E, F, G, A, B in that order. Line 45 U 
PLAYS the same notes as line 30, but it specifies the SID control 

characters U5 as volume level 5, V2 as voice 2 and 05 as octave 5. , | 

Remember, the SID control characters allow you to change the syn- I I 

thesizer controls within a string and exercise the most control over 

the synthesizer. Line 65 specifies the control characters U7 for vol- ; . 

ume level 7, V3 for voice 06 for octave 6 and XO to turn off the filter. I ! 

Line 65 PLAYS the same notes as lines 30 and 45, but in a different 

volume, voice and octave. I I 

Line 85 has the same volume and octave as line 65, and it specifies 

half notes for the notes and D, quarter notes for the notes E and F, , , 

eighth notes for notes G and A and a sixteenth note for the B note. 1 I 

Line 1 05 sets the volume at 8, voice 1 , octave 4 and turns off the 

filter. It also specifies the note as a dotted half note, E as a sharp , | 

quarter note, G and A as flat eighth notes and B as a dotted sharp I I 

sixteenth note. 

u 

Advanced Filtering 

Each of the previous FILTERing examples used only one filter at a j I 

time. You can combine the SID chip's three filters with each other to ' — ' 
achieve different filtering effects. For example, you can enable the 

low-pass and high-pass filters at the same time to form a notch j j 

reject filter. A notch reject filter allows the frequencies below and ' — ' 
above the cutoff to pass through the SID chip, while the frequencies 

close to the cutoff frequency are filtered. See Figure 7-1 for a i j 
graphic representation of a notch reject filter. 

u 
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Figure 7-10. Notch Reject Filter 

You can also add either the low-pass or high-pass filter to the band- 
pass filter to obtain interesting effects. By nnixing the band-pass filter 
with the low-pass filter, you can select the band of frequencies 
beneath the cutoff frequency and below. The rest are filtered out. 

By nnixing the band-pass and the high-pass filters, you can select the 
band of frequencies above the cutoff frequency and higher. All the 
frequencies below the cutoff are filtered out. 

Experiment with the different combinations of filters to see all the 
different types of accents you can place on your musical notes and 
sound effects. The filters are designed to perfect the sounds created 
by the other components of the SID chip. Once you have created the 
musical notes or sound effects with the SID chip, go back and add 
the FILTERing to your programs to make them as crisp and clean as 
possible. 

Now you have all the information you need to write your own musical 
programs in Commodore 128 BASIC. Experiment with the different 
waveforms, ADSR settings, TEMPOS and FILTERing. Look in a book 
of sheet music and enter the notes from a musical scale in sequence 
within a play string. Accent the notes in the string with the SID con- 
trol characters. You can combine your Commodore 128 music syn- 
thesizer with 01 28 mode graphics to make your own videos or "mov- 
ies," complete with sound tracks. 
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Coding A Song 
from Sheet Musio 
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This section provides a sample piece of sheet music and illustrates 
how to decode notes from a musical staff and translate them into a 
form the Commodore 128 can understand. This exercise is substan- 
tially faster and easier if you know how to read music. However, you 
don't have to be a musician to be able to play the tune on your Com- 
modore 128. For those of you who cannot read music, Figure 7-11 
shows how a typical musical staff is arranged and how the notes on 
the staff are related to the keys on a piano. 
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Figure 7-11. Musical Staff 

Figure 7-12 is an excerpt from a composition titled Invention 13 
(Inventio 13 in Italian), by Johann Sebastian Bach. Although this com- 
position was written a few hundred years ago, it can be played and 
enjoyed on the most modern of computer synthesizers, such as the 
SID chip in the Commodore 1 28. Here are the opening measures of 
Invention 13. 



©COPYRIGHT 
SHEET MUSIC COURTESY 
OF C.F. PETERS, CORR. 
NEW YORK 



Inventio 13 
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Figure 7-12. Part of Bach's Invention 13 
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The best way to start coding a song into your Commodore 1 28 is by 
breaking the notes down into an intermediate code. Write down the 
upper staff notes on a piece of paper. Now write down the notes for 
the lower staff. Precede the note values with a duration code. For 
instance, precede an eighth note with an 8, precede a sixteenth note 
with a 16, and so on. Next, separate the notes so the notes on the 
upper staff for one measure are proportional in time with the notes 
for one measure on the lower staff. 
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If the musical composition had a third staff, you would separate it so 
the duration is proportional to the two other upper staffs. Once the 
notes for all the staffs are separated into equal durations, a separate 
dedicated voice would play each note for a particular staff. For 
example, voice 1 would play the upper staff, voice 2 will play the 2d 
staff and voice 3 would play the lowest staff if it existed. 

Let's say the upper staff begins with a string of four eighth notes. In 
addition, say the lower staff begins with a string of eight sixteenth 
notes. Since an eighth note is proportional in time to two sixteenth 
notes, separate the notes as shown in Figure 7-13. 



V1 = 8A 



8B 



8C 



8D 
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V2= 16D16E 16F16G 16A16B 16C16D 

Figure 7-13. Synchronizing Notes for Two Voices 

Since the synchronization and timing in a musical composition is 
critical, you must make sure the notes in the upper staff for voice 1 , 
for example, are in time agreement with the notes in the lower staff 
for voice 2. The first note in the upper staff in Figure 7-1 3 is an A 
eighth note. The first two notes for voice 2 are D and E sixteenth 
notes. In this case, you must enter the voice 1 eighth note in the 
PLAY string first, then follow the voice 2 sixteenth notes immediately 
after it. To continue the example, the second note in Figure 7-1 3 for 
voice 1 (the upper staff) is a B eighth note. The B eighth note is equal 
in time to the two sixteenth notes, F and G, which appear in the bot- 
tom staff for voice 2. In order to coordinate the timing, enter the B 
eighth note in the string for voice 2 and follow it with the two six- 
teenth notes, F and G, for voice 2. 
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As a rule, always start with the note with the longer duration. For 
exannple, if a bar starts with a series of two sixteenth notes on the 
lower staff for voice 2 and the upper staff starts with an eighth note 
for voice 1 , enter the eighth note in the string first since it nnust play 
for the duration while the two sixteenth notes are being fetched by 
the Comnnodore 1 28. You must give the connputer tinne to play the 
longer note first, and then PLAY the notes of shorter duration, or else 
the composition will not be synchronized. 

Here's the program that plays Invention 13. Enter it into your CI 28, 
SAVE it for future use, and then RUN it. 



L I 
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10 REM INVENTION 13 BY BACH 
20 TEMPO 6 

PLAY"V104T7U8XO":REM VOICE 1=0RGAN 

PLAy"V2O4T0U8X0":REM VOICE 2=PIAN0 

REM FIRST MEASURE 

AS="V201IAV103IEV202QAV103SA04C03BEV202I#GV103SB04DV104ICV202SAEM" 

B$="V104IEV202SA03CV103I#GV202SBEV104IEV202SB03D" 
80 REM SECOND MEASURE 

90 C$="V203ICV103SAEV202IAV103SA04CV202I#GV103SBEV202IEV103SB04D" 
100 D$="V104ICV202SAEV103IAV202SA03CV104QRV202SBEB03D" 
110 REM REM THIRD MEASURE 
120 E$="V203ICV104SREV202IAV104SCEV203ICV103SA04CV202IAV102SEG" 

F$=="V103IFV203SD02AV103IAV202SFAV104IDV202SDFV104IFV201SA02C" 
REM FOURTH MEASURE 

G$="V201IBV104SFDV202IDV103SB04DV202IGV103SGBV202IBV103SDF" 
H$="V103IEV202SGEV103IGV202SEGV104ICV202SCEV104IEV201SGB" 
170 REM FIFTH MEASURE 

180 I$="V2OlIAV104SECV202ICVlO3SAO4CVlO3lFV2O2SDFVlO4IDV2OlSBO2D" 
190 J$="V201IGV103SDBV201IBV103SGBV103IEV202SCEV104ICV201SA02C" 
REM SIXTH MEASURE 

K$ = "V201IFV104SC03AV201IDV103SFAV103IDV201SG02GV103IBV202SFG" 
M$="V201IAV104SC03AV202I#FV104SCEV201IBV104SD03BV202I#GV104SDF" 
230 REM SEVENTH MEASURE 

240 N$="V202ICV104SECV202IAV104SEGV202IDV104SFEV202I$BV104SDC" 
250 0$="V202l#GV103SB04CV202lFVl04SDEV202iDVl04SFDV201IBVl04S#GD" 
260 REM EIGHTH MEASURE 

P$="V202I#GV104SBDV202IAV104SCAV202IDV104SFDV202IEV103SB04D" 

Q$="V202IFV103S#GBV202I#DV104SC03AV202IEV103SEAV202IEV103SB#G" 

REM NINTH MEASURE 

R$="V201HAV103SAECE02QA" 

PLAY A$:PLAY B$:PLAY C$:PLAY D$:PLAY E$ 

PLAY F$ : PLAY G$ : PLAY H$ : PLAY 1$ : PLAY J$ 

PLAY K$:PLAY M$:PLAY N$:PLAY 0$:PLAY P$ 

PLAY Q$:PLAY R$ 
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You can use the techniques described in this section to code your 
favorite sheet nnusic and play it on your Connnnodore 1 28. 

••••••**•*•**•••*•**********••••*••*•••*•••••••••••*•* 

You now have been introduced to most of the powerful new conn- 
mands of the BASIC 7.0 language that you can use in C128 mode. In 
the following section you will learn to use both 40- and 80-column 
screen displays with the Commodore 128. 
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SECTION 8 
Using 80 Columns 
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INTRODUCTION 

THE 40/80 KEY 

VIDEO PORTS AND MONITORS 
Connecting a Monitor 
Types of Monitors 

Composite Monitors 
RGBI Monitors 
Dual Monitors 

USING PREPACKAGED 80-COLUMN SOFTWARE 

CREATING 80-COLUMN PROGRAMS 

USING 40 AND 80 COLUMNS TOGETHER 
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Introduction 
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The 40/80 Key 



In CI 28 and CP/M modes, you can choose between a 40- and 80- 
colunnn screen display. You can even use both in a single progrann. 

Each screen size has special uses. The 40-column screen is the 
same size screen the Commodore 64 uses. With the 40-column 
screen you can use the Commodore 1 28's full graphics capabilities. 
You can draw circles, graphs, sprite characters, boxes and other 
shapes in high-resolution or multicolor graphic modes. You can also 
use sprites. 

If you are using an 80-column display you get twice the number of 
characters per screen line. In 80-column mode, you can use the 
standard graphic characters and colors available through the 
keyboard. 

You can also write programs using two monitors to take advantage 
of both screen display formats with each monitor screen performing 
different aspects of the program. For example, text output could be 
displayed on the 80-column monitor while graphics output could be 
seen on the 40-column monitor. 



You can use the 40/80 key to set the screen width as either 40 or 80 
columns. Pressing this key will only have an effect when one of the 
following actions is taken: 

1. Power is turned ON. 

2. The RESET button is pressed. 

3. The RUN/STOP and RESTORE keys are pressed simultane- 
ously 

The 40/80 key acts like a SHIFT/LOCK key: it locks when you press it, 
and does not release until you press it again. If this key is up (not 
pressed) when one of the three conditions above occurs, the screen 
is set to 40 columns. If before power-up you press the key down, 
causing it to lock, and one of the three conditions listed above then 
occurs, the screen is set to 80 columns. Once the computer is run- 
ning in one screen format (40 or 80 columns), you cannot switch to 
the other format using the 40/80 key In this case you must press and 
release the ESC key and then press the X key 
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Video Ports and 
Monitors 



Connecting a IMIonitor 

Make sure that you connect your monitor properly to the ports on the 
back of your connputer. There are two openings: one is labeled 
VIDEO and one is labeled RGBI. 




VIDEO is the connecting port for 40-column composite video moni- 
tors while RGBI is used for 80-column monitors. Dual monitors like 
the Commodore 1902, which can display either 40-column compos- 
ite or 80 column RGBI screens, are connected to both ports. 

Types of IMonitors 



Composite Composite monitors are designed to display 40- 

iflonitors column output on their screens. Examples of 

composite monitors are the Commodore 1 701 
and 1702 monitors. These monitors can be used 
for all 40-column programs and programming in 
all three modes. However, they cannot be used 
for 80-column work. 
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Using 

Prepackaged 80- 
Column Software 



I I 



Creating 80- 
Column Programs 
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RGBI Monitors 



Dual IMonitors 



RGBI monitors are specially designed to display 
80-colunnn output. Although RGBI stands for 
Red Green Blue Intensity RGBI nnonitors can be 
either color or nnonochrome (single color). The 
nnost popular nnonochrome monitors use green 
or amber displays. An RGBI monitor connected 
to the RGBI port can handle 80-column output in 
both CI 28 and CP/M modes. 

Dual monitors like the Commodore 1902 can 
provide either a composite video (40-column) or 
RGBI (80-column) display A dual monitor con- 
nects to both video ports. A switch on the moni- 
tor lets you select either screen output. The 40/ 
80 key on your computer determines the type of 
screen display upon power-up. Make sure the 
40/80 key setting corresponds to the 40/80 
column slide switch setting on the front control 
panel of the monitor. NOTE: You can still switch 
back and forth between 40 and 80 column out- 
put by pressing and releasing the ESC key and 
then pressing the X key regardless of which 
position the 40/80 key is in. 



Most CP/M programs utilize an 80-column screen, as do many of the 
other buisness application packages you can use in C128 mode. 
Since the width of a normal printed page is 80 columns, an 80- 
column wordprocessor can display information on the screen 
exactly as that information will appear on paper. Spreadsheet pro- 
grams often specify an 80-column format, in order to provide enough 
space for the necessary columns and categories of information. 
Many database packages and telecommunications programs also 
require or can use an 80-column screen. 



In addition to running prepackaged software, the 80-column screen 
width can be useful in designing your own programs. You've proba- 
bly noticed what happens when you type a line that is wider than 40 
columns on a 40-column screen. The lines "wrap around" — that is, 
they continue onto the next screen line. This may cause confusion in 
reading the line, and can even lead to programming errors. An 
80-column screen helps eliminate these problems. In general, 
an 80-column screen allows for a clearer screen and better 
organization. 
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Using 40 and 80 
Columns Together 



The main advantage of 40-column connposite video output is tine 
availability of bit nnapped graphics, while 80 colunnns gives you out- 
put for word processing and other business applications. If you have 
two nnonitors, you can write progranns that are "shared", using the 
text features 80 colunnns affords you and the graphics of 40 
colunnns. A special connmand, (GRAPHIC 1 ,1) can be used within a 
progrann to transfer the execution of graphics connnnands to the 40- 
colunnn display If you have a dual nnonitor (one that can display both 
40- and 80-colunnn fornnats) you can place GRAPHIC 1,1 statennents 
in your progrann so that graphics will be output in 40-colunnn screen 
fornnat. In order to view the graphic output, however, you will need to 
change the video switch on the nnonitor to 40 colunnns. If you write a 
progrann like this, it nnight be a good idea to include on-screen direc- 
tions to the user to change the video switch. 

For exannple, you nnight write a progrann which asked the user to 
input data, then created a bar graph based on the user's input. The 
message "CHANGE TO 40 COLUMN TO VIEW GRAPH" would tell 
the user to switch modes and see the results. 

As noted previously you can switch between the 80- and 40-column 
formats after power up, with the ESCape/X sequence. 



u 
u 



u 



\ I 



u 



u 
u 
u 

u 



164 



USING 0128 MODE— Using 80 Columns 



I \ 



The following example shows how dual screens can be used within a 
program: 
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10 IF RGR(0)= THEN 80:REM CHECK FOR 40 COLUMN TEXT MODE-IF TRUE GO TO iilNE 80 
20 GRAPHIC 5,1 :REM THIS STATEMENT SWITCHES TO 80 COLUMN TEXT MODE 
30 PRINT !»QST ART IN 40 COLUMN OUTPUT": PRINT? | '/ ^ic^/fJv :J^ 

40 PRINT" SLIDE THE SWITCH ON : THE FRONT OF THE 1902 DUAL MONITOR TOJ THE MII?pSE"> 
50 PRINT :PRINT"PRESS RETURN WHEN READY" 
60 GRAPHIC 0,1:REM SWITCH TO 40 COLUMN TEXT MODE 

70 PRINT :PRINT"PRESS RETURN WHEN READY ": GETKEY A$ : IF A$<> CHR$(13)THEN 70 
80 COLOR 1,5: COLOR 4,1: COLOR 0,1: REM COLOR THE SCREEN 

90 GRAPHIC 2,1 :CHAR 1,8, 18, "BIT MAP/TEXT SPLIT SCREEN":REM SELECT SPLIT SCREEN 
100 FOR 1=70 TO 220 STEP 20 :CIRCLE 1 ,1, 50 , 30, 30 :NEXT 
110 PRINT" SWITCH TO 80 COLUMN OUTPUT" 

120 PRINT" SLIDE THE MONITOR SWITCH ON THE FRONT TO THE EXTREME RIGHT'' 
130 PRINT'! PRESS THE RETURN KEY WHEN READY" : GETKEY A$:IF A$<> CHRS ( 1 3 ) THElsi 130 
140 GRAPHIC 5,1 :REM THIS STATEMENT SWITCHES TO 80 COLUMN TEXT MODE 
150 FOR J==1T0 10 

-1:60/ PRINTi" NOW- -YOU ARE IN 80 COLUMN TEXT OUTPUT" \ , . - >>/".; . 

170 NEXT -PRINT ..;: V 

180 PRINT"NOW SWITCH BACK TO 40 COLUMN OUTPUT" : PRINT 

190 PRINT"SLIDE THE SWITCH ON THE FRONT OF THE MONITOR TO THE MIDDLE" :PRINT 
200 PRINT"PRESS THE RETURN KEY WHEN READY" :GETKEY A$:IF A$<> CHR$(13)THEN 200 
i210 GRAPHIC 0,1:REM THIS STATEMENT SWITCHES TO 40 COLUMN TEXT MODE 
220 FOR J=1T0 70 

230 PRINT "NOW YOU ARE IN 40 COLUMN TEXT MODE" 
240 NEXT 



I \ 



Each screen display format offers certain advantages; yet the two 
types of displays can be combined in a program to complement 
each other. Using a 40-column screen, you get the full power of 
advanced BASIC graphics. The 80-column display gives you more 
space for your own programs. In addition, it lets you run the wide 
variety of software designed to run on an 80-column screen. 

•••••*•••••••••*•••••••*•••••••••*•*•••**••••••••*•••• 

The sections of this chapter have introduced you to the many fea- 
tures and capabilities provided by the Commodore 128 in C128 
mode. The following chapter tells you how to use the Commodore 
128 in C64 mode. 
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SECTION 9 
Using the 
Keyboard In C64 
Mode 



USING BASIC 2.0 

KEYBOARD CHARACTER SETS 

USING THE TYPEWRITER-STYLE KEYS 

USING THE COMMAND KEYS 

MOVING THE CURSOR IN C64 MODE 

PROGRAMMING FUNCTION KEYS IN C64 MODE 
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Keys 



Using The 
Command Keys 



Nloving The 
Cursor In C64 
Mode 
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The entire BASIC 2.0 language built into the Commodore 64 com- 
puter has been incorporated into the BASIC 7.0 language of the 
Commodore 128. You can use the BASIC 2.0 commands in both 
C128 and C64 modes. Refer to Sections 3 and 4 in Chapter II for a 
description of these commands. 



In the keyboard illustration in Section 3, the shaded keys are the 
ones that can be used in C64 mode. The keyboard in C64 mode has 
the same two character sets as in C128 mode: 

— Upper-case/graphic character set 
— Upper/lower-case character set 

When you enter C64 mode, the keyboard is in the upper-case/ 
graphic character set, so that everything you type is in capital let- 
ters. In C64 mode you can only use one character set at a time. To 
switch back and forth between character sets, press the SHIFT key 
and the & key (the COMMODORE key) at the same time. 



As in 0128 mode, you can use the typewriter-style keys in 064 mode 
to type both upper-case letters (capitals) and lower-case letters 
(small letters). You can also type the numerals shown on the top row 
of the main keyboard. In addition, you can type the graphics symbols 
on the fronts of the keys. 



Most COMMAND keys (i.e., the keys that send messages to the com- 
puter, like RETURN, SHIFT CTRL, etc.) work the same in 064 mode 
as they do in 0128 mode. 

The only difference is that in 064 mode, you can only move the cur- 
sor by using the two ORSR keys at the bottom-right corner of the 
main keyboard. (In 0128 mode, you can also use the four arrow keys 
located just above the top right side of the main keyboard.) 



In 064 mode, you use two ORSR keys on the main keyboard and the 
SHIFT key to move the cursor, as described in Section 3. 
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Programming 
Function Keys In 
C64 Mode 



The four keys to the right side of the l<eyboard, just above the 
numeric keypad, are called function keys. The keys are marked F1, 
F3, F5 and F7 on the tops and F2, F4, F6 and F8 on the fronts. These 
keys can be programmed — that is, they can be instructed to per- 
form a specific task or function. For this reason, these keys are 
often called programmable function Iceys. 

You must hold down the SHIFT key to perform the functions associ- 
ated with the markings on the front of the keys — that is, F2, F4, F6 
and F8. Therefore, these keys are sometimes called the SIHIFTed 
programmable function keys. 

The function keys in C64 mode do not have a printed character 
assigned to them. They do, however, have CHR$ codes assigned. In 
fact, each of them has two CHR$ codes — one for when you press 
the key by itself, and one for when you press the key while holding 
down the SHIFT key To get the even-numbered function keys, hold 
down the SHIFT key while pressing the function key For example, to 
get F2, hold down SHIFT and press F1. 

The CHR$ codes for the F1-F8 keys range from 133 to 140. However, 
the codes are not assigned to the keys in numerical order. The keys 
and their corresponding CHR$ codes are as follows: 

F1 CHR$(133) 

F2 CHR$(137) 

F3 CHR$(134) 

F4 CHR$(138) 

F5 CHR$(135) 

F6 CHR$(139) 

F7 CHR$(136) 

F8 CHR$(140) 

You can use the function keys in your program in several ways. To do 
this, you'll need to use the GET statement. (See Section 4 for a 
description of the GET statement.) As an example, the program 
below prepares the F1 key to print a message on the screen. 

10 ? "PRESS F1 TO CONTINUE" 

20 GETA$ 

30 IF A$< >GHR$(133) THEN 20 

40 ? "YOU HAVE PRESSED F1" 
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Lines 20 and 30 do most of the work in this progrann. Line 20 nnakes 
the computer wait until a key is pressed before executing any more 
of the program. Note that when the command immediately after 
THEN is a GOTO, only the line number is necessary Also note that a 
GOTO command can GOTO the same line it is on. Line 30 tells the 
computer to go back and wait for another key to be pressed unless 
the F1 key has been pressed. 
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FORMATTING A DISK IN C64 MODE 

THE SAVE COMMAND 
SAVEing on Disk 
SAVEing on Cassette 

THE LOAD AND RUN COMMANDS 
LOADing and RUNning from Disk 
LOADing and RUNning from Cassette 

OTHER DISK-RELATED COMMANDS 
Verifying a Program 
Displaying Your Disk Directory 
Initializing a Disk Drive 
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The SAVE 
Command 



Once you have edited a program, you will probably want to store it 
permanently so that you will be able to recall and use it at some later 
time. To do this you'll need either a Commodore disk drive or the 
Commodore Datassette. 



To store programs on a new (or blank) disk, you must first prepare the 
disk to receive data. This is called formatting the disk. Make sure that 
you turn on the disk drive before inserting any disk. 

To format a blank disk in C64 mode, you type this command: 



OPEN 15,8,15: PRINT# 15,"N0:NAME,ID" RETURN 

In place of NAME, type a disk name of your choice; you can use up 
to 16 characters to identify the disk. In place of ID, type a two- 
character code of your choice (such as W2 or 10). 

The cursor disappears during the formatting process. When the cur- 
sor blinks again, type the following command: 



CLOSE 15 ; 

NOTE: Once a disk is formatted in C64 or C128 mode, that disk can 
be used in either mode. 



You can use the SAVE command to store your program on disk 
or tape. 



SAVEing on Disk 

If you have a Commodore disk drive, you can store your program on 
disk by typing: 

SAVE "PROGRAM NAME",8 III Mlllll 

The 8 indicates to the computer that you are using a disk drive to 
store your program. 

The same rules apply for the PROGRAM NAME whether you are 
using disk or tape. The PROGRAM NAME can be anything you want 
it to be. You can use letters, numbers and/or symbols— up to 16 
characters in all. Note that you must enclose the PROGRAM NAME 
in quotation marks. The cursor on your computer disappears while 
the program is being SAVEd, but it returns when the process is com- 
pleted. 
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The LOAD and 
RUN Commands 



SAVEing on Cassette 

If you are using a Datassette to store your program, insert a blank 
tape in the recorder, rewind the tape (if necessary) and type: 

SAVE "PROGRAM NAME" 



Once a progrann has been SAVEd, you can LOAD it back into the 
connputer's nnennory and RUN it anytinne you wish. 

LOADing and RUNning from Disk 

To load your program from a disk, type: 

LOAD"PROGRAM NAME",8 ULIUHN 

Again, the 8 indicates to the computer that you are working with a 
disk drive. 



To RUN the program, type RUN and press <RETURN>. 

LOADing and RUNning from Cassette 

To LOAD your program from cassette tape, type: 
LOAD "PROGRAM NAME" nrTlinfl 

If you do not know the name of the program, you can type: 

and the next program on the tape will be retrieved. 

You can use the counter on the Datassette to identify the starting 
position of the programs. Then, when you want to retrieve a pro- 
gram, simply wind the tape forward from 000 to the program's start 
location, and type: 

In this case, you don't have to specify the PROGRAM NAME; your 
program will load automatically because it is the next program on 
the tape. 

NOTE: During the LOAD process, the program being LOADed 
is not erased from the tape; it is simply copied into the com- 
puter. However, LOADing a program automatically erases any 
BASIC program that may have been in the computer's memory. 

To RUN the program, type RUN and press (RETURN). 
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Other Disk- 
Related 
Commands 



Verifying A Program 

To verify that a program has been correctly saved or loaded, type: 

VERIFY"PROGRAM NAME",8 HU V HM 

If the program in the computer is identical to the one on the disk, the 
screen display will respond with the letters "OK." 

The VERIFY command also works for tape programs. You type: 

VERIFY"PROGRAM NAME" nCTURN 

Note that you do not need to enter the comma and the number 8, 
since 8 indicates that you are working with a disk program. 

Dispiaying Your Disic Directory 

To see a list of the programs on your disk, first type: 

The cursor disappears during this process. When the cursor re- 
appears, type: 



list; 

A list of the programs on your disk will then be displayed. Note that 
when you load the directory, any program that was in memory is 
erased. 



Initializing A Disic Drive 

If the disk drive's ready light is blinking, it indicates a disk error. You 
can restore the disk drive to the condition it was in before the error 
occurred by using a procedure called INITIALIZING. To initialize a 
drive, you type: 



OPEN 1,8,15,"l":CLOSE 1 

If the light is still blinking, remove the disk and turn the drive off, 
then on. 

For further information on SAVEing and LOADing your programs, 
refer to your disk drive or Datassette manual. Also consult the 
LOAD and SAVE command descriptions in Chapter V, BASIC 7.0 
Encyclopedia. 
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WHAT YOU NEED TO RUN CP/M 3.0 

GETTING STARTED WITH CP/M 3.0 
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CP/M is a product of Digital Research, Inc. The version of CP/M used 
on the Connnnodore 128 is CP/M Plus Version 3.0. In this chapter, 
CP/M is generally referred to as CP/M 3.0, or sinnply CP/M. This chap- 
ter summarizes CP/M on the Commodore 128. For detailed informa- 
tion on CP/M 3.0, fill out and return the order form included in this 
chapter. 

CP/M 3.0 is a popular operating system for microcomputers. As an 
operating system, CP/M 3.0 manages and supervises your comput- 
er's resources, including memory and disk storage, the console 
(screen and keyboard), printer, and communication devices. CP/M 
3.0 also manages information stored in disk files. CP/M 3.0 can copy 
files from a disk to your computer's memory or to a peripheral 
device such as a printer. To do this, CP/M 3 places various programs 
in memory and executes them in response to commands you enter 
at your console. Once in memory a program executes through a set 
of steps that instructs your computer to perform a certain task. 

You can use CP/M to create your own programs, or you can choose 
from the wide variety of available CP/M 3.0 application programs. 



The general hardware requirements for CP/M 3.0 are a computer 
containing a Z80 microprocessor, a console consisting of a keyboard 
and a display screen, and at least one floppy disk drive. For CP/M 3.0 
on the Commodore 128 Personal Computer, the Z80 microprocessor 
is built-in; the console consists of the full Commodore 1 28 keyboard 
and an 80-column monitor; and the disk drive is the new Commodore 
1 571 fast disk drive. The CP/M system is packed, in disk format, in 
the computer carton. The material on disk includes the CP/M 3.0 
system and an extensive HELP utility program, as well as a number 
of other utility programs. 

NOTE: Although CP/M can be used with a 40-column monitor, only 
40 columns can be displayed at one time. To view all 80 columns of 
the display you must scroll the screen horizontally by pressing the 
CONTROL key and the appropriate cursor key (left or right). 

CP/M can also be used with the 1541 disk drive. In this case only 
single-sided GCR disks may be used, and the speed of operation will 
be one-eighth to one-tenth the speed using the 1571 disk drive. 
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Getting Started 
With CPflM 3.0 



The following paragraphs tell you how to start or "boot" CP/M 3.0, 
how to enter and edit the comnnand line. 

NOTE: Before you start to use CP/M, you should nnake a backup 
copy of your CP/M disk data. Follow the procedure for copying disks 
described in Section 12. 



Loading Or Booting CPflM 3.0 

Loading or "booting" CP/M 3.0 nneans reading a copy of the operat- 
ing systenn f ronn your CP/M 3.0 system disk into your connputer's 
nnemory 

You can boot CP/M 3.0 in several ways. If your connputer is off, you 
can boot CP/M by first turning on your disk drive and inserting the 
CP/M 3.0 system disk, and then turning on the computer. CP/M 3.0 
will load automatically If you are already in C128 BASIC mode, you 
can boot CP/M 3.0 by inserting the CP/M system disk into the drive 
and then typing the BASIC command BOOT. CP/M 3.0 will then load. 
In 01 28 mode, you can also boot CP/M by inserting the system disk 
and pressing the RESET button. 

If you are in 064 mode, and you want to enter CP/M mode, first turn 
off the computer. Then load the CP/M system disk in the drive and 
turn on the computer. 

Caution: Always make sure that the disk is fully inserted in the 1571 
drive before you close the drive door. 

In CP/M 3.0 on the Commodore 128, the user has a 59K TPA (Tran- 
sient Program Area), which in effect is user RAM. 



Tlie Opening CPflM Screen Display 

After CP/M 3 is loaded into memory a message similar to the follow- 
ing is displayed on your screen. (The screen shown here is the 
80-column format.) 
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An important part of the opening display is tine following two- 
character message: 

A> 

This is the CP/M 3.0 system prompt. The system prompt tells you 
that CP/M is ready to read a command entered by you from your 
keyboard. The prompt also tells you that drive A is your default drive. 
This means that until you tell CP/M to do otherwise, it looks for pro- 
gram and data files on the disk in drive A. It also tells you that you are 
logged in as user (the default user number, indicated by the 
absence of any user number). 

NOTE: In CP/M a single disk drive is identified as drive A. This is 
equivalent to unit number 8, drive in C128 and C64 modes. Usually 
the maximum number of drives in CP/M 3.0 is 1 6. However, on the 
Commodore 1 28 the number of drives is limited to four physical 
drives, identified as A, B, C or D) and one logical or virtual drive, 
identified as drive E. See page 1 98 for more information on the 
virtual drive E. 
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The Command 
Line 



CP/M 3.0 performs tasks according to specific commands tliat you 
type at your keyboard. These commands appear on tine screen in 
what is called a command line- A CP/M 3.0 command line is com- 
posed of a command keyword and an optional command tail. The 

command keyword identifies a command (program) to be executed. 
The command tail can contain extra information for the command, 
such as a filename or parameters. The following example shows a 
command line. 

A>D/B MYFILE 

Throughout this chapter, the characters that a user would type are in 
slanted (italic) bold face type to distinguish them from characters 
that the system displays. In this example, DIR is the command key- 
word and MYFILE is the command tail. To send the command line to 
CP/M 3.0 for pro cessing, pres s the RETURN key as indicated in 
this book by the HhlUHN l symbol. 

As you type characters at the keyboard, they appear on your screen. 
The cursor moves to the right as you type. If you make a typing error, 
press either the INST/DEL key or CTRL-H to move the cursor to the 
left and correct the error. CTRL is the abbreviation for the CONTROL 
key To specify a control character, hold down the CTRL key and 
press the appropriate letter key (A list of control characters and their 
uses is given in Section 1 3.) 

You can type the keyword and command tail in any combination of 
upper-case and lower-case letters. CP/M 3.0 interprets all letters in 
the command line as uppercase. 

Generally you must type a command line directly after the system 
prompt. However, CP/M 3.0 does allow spaces between the prompt 
and the command keyword. 
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lypes Of Commands 

CP/M 3.0 recognizes two different types of commands: built-in com- 
mands and transient utility commands. Built-in commands execute 
programs that reside in memory as a part of the CP/M operating 
system. Built-in commands can be executed immediately Transient 
utility commands are stored on disk as program files. They must be 
loaded from disk to perform their task. You can recognize transient 
utility program files when a directory is displayed on the screen 
because their filenames are followed by a period and COM (.COM). 
Section 14 presents lists of the CP/M built-in and transient utility 
commands. 
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For transient utilities, CP/M 3.0 cliecks only the connnnand keyword. 
Many utilities require unique comnnand tails. If you include a conn- 
nnand tail, CP/M 3.0 passes it to the utility without checking it. A 
connnnand tail cannot contain nnore than 128 characters. 



How CPIM Reads Command Lines 

Let's use the DIR connmand to dennonstrate how CP/M reads conn- 
nnand lines. DIR, which is an abbreviation for directory tells CP/M to 
display a directory of disk files on your screen. Type the DIR keyword 
after the systenn pronnpt, and press RETURN: 

CP/M responds to this connnnand by displaying the nannes of all the 
files that are stored on whatever disk is in drive A. For exannple, if the 
CP/M systenn disk is in disk drive A, a list of f ilenannes like this 
appears on your screen: 

A:CPM+ SYS:CCP CGMiHELP CGMiHELP HLPiKEYFIG COM 

AiKEYFIG HLP:FGRMAT CGMiPIP CGMiDIR CGMiCGPYSYS CGM 

CP/M 3.0 recognizes only correctly spelled comnnand keywords. If 
you make a typing error and press RETURN before correcting your 
mistake, CP/M 3.0 repeats or "echoes" the command line, followed 
by a question mark. For example, suppose you mistype the DIR 
command, as in the following example: 

CP/M replies with: 

DJR? 

This tells you that CP/M cannot find a command keyword spelled 
DJR. To correct typing errors like this, you can use the INST/DEL key 
to delete the incorrect letters. Another way to delete characters is to 
hold down the CTRL key and press H to move the cursor to the left. 
CP/M provides a number of other control characters that help you 
edit command lines. Section 13 tells how to use control characters 
to edit command lines and other information you enter at your 
console. 

DIR accepts a filename as a command tail. You can use DIR with a 
filename to see if a specific file is on the disk. For example, to check 
that the file program MYFILE is on your disk, type: 

A>D/R MYFILE \ 
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CP/M 3.0 performs this task by displaying either the name of the file 
you specified, or the message: 

No File 

Be sure you type at least one space after DIR to separate the com- 
mand keyword from the command tail. If you do not, CP/M 3.0 re- 
sponds as follows: 

A)DIRMYFILE \ 
DIRMYFILE? 



u 
u 
u 
u 

NOTE: The Digital Research Inc. COPYSYS command, normally 
used in copying CP/M systems disks, is not implemented on your 

computer. As described in Section 1 3, page 1 99, your Commodore j j 

128 uses a different method to prepare a new system disk. To obtain 
information on this method, type: 

HELP COPYSYS L-i 

at any system prompt. Be sure to include a space between HELP 

and COPYSYS. j_j 

u 
u 
u 
u 
u 
u 
u 
u 
u 
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What Is A File? 



Creating A File 



Naming A File 



One of CP/M's most important tasks is to access and maintain files 
on your disks. Files in CP/M are fundamentally the same as in CI 28 
or C64 modes — that is, they are collections of information. However, 
CP/M handles files somewhat differently than do C1 28 and C64 
modes. This section defines the two types of files used in CP/M; tells 
how to create, name and access a file; and describes how files are 
stored on your CP/M disks. 

As noted above, a CP/M 3.0 file is a collection of information. Every 
file must have a unique name by which CP/M identifies the file. A 
directory is also stored on each disk. The directory contains a list of 
the filenames stored on that disk and the locations of each file on the 
disk. 

There are two kinds of CP/M files: program (command) files, and 
data files. A program file contains a series of instructions that the 
computer follows step-by-step to achieve some desired result. A 
data file is usually a collection of related information (e.g., a list of 
names and addresses, the inventory of a store, the accounting 
records of a business, the text of a document). 



There are several ways to create a CP/M file. One way is to use a text 
editor. The CP/M text editor ED is used to create and name a file. You 
can also create a file by copying an existing file to a new location; 
you can rename the file in the process. Under CP/M, you can use the 
PIP command to copy and rename files. Finally some programs 
(such as MAC, a CP/M machine language program) create output 
files as they process input files. 

The ED and PIP commands are summarized in Section 14, together 
with other commonly used CP/M commands. Details on these and all 
other CP/M 3.0 commands may be found in the CP/M Plus User's 
Guide, which you can obtain by responding to the offer on the card 
inserted in this chapter. 



File Specification 

CP/M identifies every file by a unique file specification. A file speci- 
fication can have four parts: a drive specifier, a filename, a file- 
type and a password. The only mandatory part is the filename. 
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Drive Specifier 



Filename 



Filetype 



The drive specifier is a single letter (A-P) fol- 
lowed by a colon. Each disk drive in your systenn 
is assigned a letter. When you include a drive 
specifier as part of the file specification, you are 
telling CP/M to look for the file on the disk cur- 
rently in the specified drive. For exannple, if you 
enter: 

BiMYFILE III lllllll 

CP/M looks in drive B for the file MYFI LE. If you 
onriit the drive specifier, CP/M 3.0 looks for the 
file in the default drive (usually A). 

A f ilenanne can be f ronn one to eight characters 
long, such as: 

MYFILE 

A file specification can consist sinnply of a 
f ilenanne. When you nnake up a f ilenanne, try to 
let the nanne tell you sonnething about what the 
file contains. For exannple, if you have a list of 
customer names for your business, you could 
name the file: 

CUSTOMER 

SO that the name gives you some idea of what is 
in the file. 



To help you identify files belonging to the same 
category CP/M allows you to add an optional 
one- to three-character extension, called a file- 
type, to the filename. When you add a filetype to 
the filename, separate the filetype from the 
filename with a period. Try to use letters that tell 
something about the file's category For exam- 
ple, you could add the following filetype to the 
file that contains a list of customer names: 

CUSTOMER.NAM 

When CP/M displays file specifications, it adds 
blanks to short filenames so that you can com- 
pare f iletypes quickly The program files that 
CP/M loads into memory from a disk have the 
filetype COM. 
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Password 



In the Commodore 128's CP/M 3.0 you can 
include a password as part of the file specifica- 
tion. The password can be from one to eight 
characters. If you include a password, separate 
it from the f iletype (or filename, if no f iletype is 
included) with a semicolon, as follows: 

CUSTOMER.NAM;ACCOUNT 

A password is optional. However, if a file has 
been protected with a password, you MUST 
enter the password as part of the file specifica- 
tion to access the file. 



Sample File A file specification containing all four possible 

Specification elements consists of a drive specification, a 

primary filename, a f iletype and a password, all 
separated by the appropriate characters or 
symbols as in the following example: 

A:DOCUMENT±AW;SUSAN HHimM 

User Number 

CP/M 3.0 further identifies all files by assigning each one a user 
number which ranges from to 1 5. CP/M 3.0 assigns the user num- 
ber to a file when the file is created. User numbers allow you to sepa- 
rate your files into 16 file groups. 

The user number always precedes the drive identifier except for 
user 0, which is the default user number and is not displayed in 
the prompt. Here are some examples of user numbers and their 
meanings. 



4A> 

A> 

2B> 



User number 4, drive A 
User number 0, drive A 
User number 2, drive B 



You can use the built-in command USER to change the current user 
number like this: 

A> USER ! 

The screen displays: 
ENTER USER #: 

You enter a 3 and press \ 
3A> 



1. The screen display is then: 
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u 

If you want to return to the normal A> prompt, you simply enter the 1 j 

USER command, like this: 



3A> USER \ 



u 

u 
u 
u 



The screen prompts you to: 
ENTER USER #: 

If you then enter a 0, the screen prompt returns to the A> format. 

Most commands can access only those files that have the current 
user number. However, if a file resides in user and is marked with a 
system file attribute, the file can be accessed from any user number. 

Using Wildcard Cliaracters to Access IMore Tlian One File 

Certain CP/M 3.0 built-in and transient commands can select and j j 

process several files when special wildcard characters are included 
in the filename or f iletype. A wildcard is a character that can be used 
in place of some other characters. CP/M 3.0 uses the asterisk (*) and j | 
the question mark (?) as wildcards. For instance, if you use a ? as the 
third character in a filename, you are telling CP/M to let the ? stand 
for any character that may be encountered in that position. Similarly 11 

an * tells CP/M to fill the filename with ? question marks as indicated. 
A file specification containing wildcards is called an ambiguous files- 
pec and can refer to more than one file, because it gives CP/M 3.0 a 11 
pattern to match. CP/M 3.0 searches the disk directory and selects 
any file whose filename or f iletype matches the pattern. For exam- 
ple, if you type: I j 

A> ?????TAX±IB 

then CP/M 3.0 selects all files whose filename end in TAX and whose j | 

filetypeis.LIB. 

u 

Reserved Characters 



( 1 



The characters in Table 1 2-1 have special meaning in CP/M 3.0, so . , 

do not use these characters in file specifications except as indi- ' — ' 

cated. 

u 



u 
u 
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Table 12-1. CP/M 3.0 Reserved Characters 



Character 

<$J|>[] 
tab space 
carriage return 



[] 



/$ 



\ + - 



Meaning 

file specification delinniters 

drive delimiter in file specification 
f iletype delimiter in file specification 
password delimiter in file specification 
comment delimiter at the beginning of a com- 
mand line 

wildcard characters in an ambiguous file specifi- 
cation. 

option list delimiters 
option list delimiters for global and local options. 

delimiters for multiple modifiers inside square 
brackets for options that have modifiers. 

option delimiters in a command line. 
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Reserved Filetypes 

CP/M 3.0 has already established several file groups. Table 12-2 lists 
some of their filetypes with a short description of each. 

Table 12-2. CP/M 3.0 Reserved Filetypes 

Filetype Meaning 

ASM Assembler source file 

BAS BASIC source program 

COM Z80 or equivalent machine language program 

HEX Output file from MAC (used by HEXCOM) 

HLP HELP message file 

$$$ Temporary file 

PRN Print file from MAC or RMAC 

REL Output file from RMAC (used by LINK) 

SUB List of commands to be executed by SUBMIT 

SYM Symbol file from MAC, RMAC or LINK 

SYS System file 

RSX Resident System Extension (a file automatically 
loaded by a command file when needed) 

USING CPim MODE-Files, Disks and Disk Drives in CP/M 3.0 



CP/M System 
Files 



CPM + . SYS 



CCR COM 



Other 

. COM Files 
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The following information is innportant for technically oriented users 
who nnay want to create their own programs in CP/M mode. 



CPM + . SYS is the main CP/M 3.0 system file. It contains all parts of 
the system that remain permanently resident in memory: the Basic 
Input/Output System (BIOS), which loads into the top of memory; the 
Basic Disk Operating System (BDOS), which loads into memory 
immediately below the BIOS; and the System Parameters, which 
load into the bottom page of memory 



On booting CP/M the Console Command Processor (COP) is loaded 
into memory immediately below the BDOS. The remaining memory 
below COP and above page 0, known as the Transient Program Area 
(TPA) is the area into which applications are loaded. CP/M 3.0 on the 
C128hasaTPAof59K. 

COP processes any input in response to the system prompt (A»). It 
contains the built-in commands listed in Table 14-1, and also supports 
the 14 console editing commands listed in Table 13-1. 

Any word entered in response to the system prompt which is not one 
of the built-in commands is treated by COP as a transient command. 
When a transient command is encountered, COP attempts to find 
and execute a file whose name is the command word plus the .COM 
extension. If COP does not find such a file on the currently logged 
disk, the command word is displayed, followed by a question mark. 
COP then redisplays the system prompt. If more than one word is 
entered in response to the system prompt, all words after the first 
are treated as parameters to be passed to the transient command. 

A language or applications program is loaded and run by invoking it 
as if it were a command. All CP/M programs include a .COM file. As 
shown in the following pages, the CPM -f . SYS and COP COM files 
are contained on the CP/M system disk. 



The other . COM files are transient commands (see Table 14-2). The 
file HELP COM displays messages about the CI 28 CP/M system and 
its commands. If you are not familiar with CP/M and have no other 
manuals or books about it, you can print out any HELP you look at. 
Press CONTROL and P to send any screen output to the printer; 
press CONTROL P again to turn off this facility If you are printing and 
do not want pauses after each screen is printed, enter HELP 01 28 
CP/M [NOPAGE] and follow the directions given on the screen. 
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What Is On Your 
CP/M Disk 



You can get a list of what is on your CP/M systenn disl< by inserting a 
disl< into a disk drive and entering a DIR command. You can get a 
detailed listing of system programs, including program size and num- 
ber of records, by entering the following form of the DIR command: 

DIR [FULL] 

Shown below is a typical display in response to a DIR [FULL] 
COMMAND. 



Directory For Drive A: User 

Name Bytes Recs Attributes 



Name 



Bytes 



Recs 



Attributes 



CCP COM 4k 

CPM+ SYS 23k 

F0R^4AT COM 5k 

HELP HLP 83k 

KEYFIG HLP 9k 

Total Bytes 
Total Ik Blocks = 



25 Dir RW 
184 Dir RW 

35 Dir RW 
664 Dir RW 

72 Dir RW 



COPYSYS COM 

DIR COM 

HELP COM 

KEYFIG COM 

PIP COM 



Ik 
15k 

7k 
10k 

9k 



3 Dir RW 

114 Dir RW 

56 Dir RW 

75 Dir RW 

68 Dir RW 



166k 
166 



Total Records = 1296 Files Found = 10 
Used/Max Dir Entries For Drive A: 16/ 64 



How To Make 
Copies Of Your 
CP/M 3.0 Disks 
And Fiies 



You can back up your CP/M 3.0 disks, using eitiier one or two disk 
drives. Tine back-up disks can be new or used. You nnight want to 
fornnat new disks, or reformat used disks witli an appropriate CP/M 
disk fornnatting progrann. If tine disks have been used previously, be 
sure that there are no other files on the disks. 

To make backups use the format and PIP utility programs found on 
your CP/M system disk. FORMAT formats the disk as either a CI 28 
single-sided or double-sided diskette. 

Making Copies Witli a Single Disk Drive 

You can copy the contents of a disk to another disk with a single 
Commodore disk drive (1541 or 1571). First type: 

A> FORMAT 

and follow the instructions given on the screen. For instance, the 
following sequence of commands creates a bootable CP/M system 
disk. First, when the copy disk is formatted, type; 

A> PIPE: = A:CPM +,SYS 

When the CPM + . SYS file is copied, you type: 

A) PIPE: = A:CCRCOM 

If you want to copy everything on a disk, use the following command 
sequence: 

A> FORMAT 

A> PIPE: = A:\* 
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The system will prompt you to change disks as required. i^ i 

Use drive A as the source drive and drive E as the destination drive. 

Drive E is referred to as a virtual drive — that is, it does not exist as i ^ 

an actual piece of hardware. ^ — ^ 

Making Copies Willi Tivo Disic Drives ^ 

This section shows how to make distribution disk back-ups on a sys- 
tem that has two drives: drive A and drive B. Your drives might be \ J 

named with other letters from the range A through D. To make a copy 
of your CP/M 3.0 system disk, first use the FORMAT utility to copy 
the operating system loader. Make sure that your distribution system 
disk is in drive A, the default drive, and the blank disk is in drive B. 
Then enter the following command at the system prompt: 

A> PIPB: =A:CPM -{-.SYS 

During the copying process, you will be prompted to place the 

source disk in drive A and the destination or copy disk in drive B. [^ 

When you have copied the CPM + SYS file you use the PIP com- 
mand to copy the CCRCOM file. You now have a copy of the operat- j j 

ing system only To copy the remaining files from the system disk, 
enter the following PIP command: 



A)PIPB: = A:\ 
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This PIP command copies all the files in your disk directory to drive B 
from drive A. PIP displays the message COPYING followed by each ^ 

filename as the copy operation proceeds. When PIP finishes copy- 
ing, CP/M 3 displays the system prompt, A>. 

\ ) 

Now you have an exact copy of the system disk in drive B. Remove 

the original system disk from drive A and store it in a safe place. As 

long as you retain the original in an unchanged condition, you will be | j 

able to restore your CP/M program files if something happens to your 

working copy 
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SECTION 13 
Using the Console 
and Printer in 
CP/M 3.0 



CONTROLLING CONSOLE OUTPUT 203 

CONTROLLING PRINTER OUTPUT 203 

CONSOLE LINE EDITING 203 

USING CONTROL CHARACTERS FOR LINE EDITING 204 
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Controlling 
Console Output 



Controlling 
Printer Output 



Console Line 
Editing 



This section describes Jiow CP/M 3.0 communicates witii your con- 
sole and printer. It tells how to start and stop console and printer 
output, and edit commands you enter at your console. 

Sometimes CP/M 3.0 displays information on your screen too quickly 
for you to read it. To ask the system to wait while you read the display 
hold down the CONTROL (CTRL) key and press S. A CTRL-S key- 
stroke sequence causes the display to pause. When you are ready 
press CTRL-Q to resume the display If you press any key besides 
CTRL-Q during a display pause, CP/M 3.0 sounds the console bell. 
Pressing the NO SCROLL key will also pause the system and place a 
pause window on the status line at the bottom of the screen (line 25). 
To resume the display press NO SCROLL again. 

Some CP/M 3.0 utilities (like DIR and TYPE) support automatic pag- 
ing at the console. This means that if the program's output is longer 
than the screen can display at one time, the display automatically 
halts when the screen is filled. When this occurs, CP/M 3.0 prompts 
you to press RETURN to continue. This option can be turned on or 
off using the SETDEF command. 

You can also use a control command to echo (that is, display) con- 
sole output to the printer. To start printer echo, press CTRL-R A beep 
occurs to tell you that echo is on. To stop, press CTRL-P again. (There 
is no beep at this point.) While printer echo is in effect, any charac- 
ters that appear on your screen are listed at your printer. 

You can use printer echo with a DIR command to make a list of files 
stored on a floppy disk. You can also use CTRL-P with CTRL-S and 
CTRL-Q to make a hard copy of part of a file. Use a TYPE command 
to start a display of the file at the console. When the display reaches 
the part you need to print, press CTRL-S to stop the display CTRL-P 
to enable printer echo, and then CTRL-Q to resume the display and 
start printing. You can use another CTRL-S, CTRL-P, CTRL-Q 
sequence to terminate printer echo. 

NOTE: Not all printers will respond properly to the CTRL-P 
command. 

As noted previously you can correct simple typing errors by using 
the I NST/DEL key or CTRL-H. CP/M 3.0 also supports additional line- 
editing functions that you perform with control characters. You can 
use the control characters to edit command lines or input lines to 
most programs. 
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Using Control 
Characters for 
Line Editing 



By using the line-editing control characters listed in Table 1 3-1 , you 
can move the cursor left and right to insert and delete characters in 
the nniddle of a comnnand line. In this way you do not have to retype 
everything to the right of your correction. 

In the following sample example, the user mistypes PIP, and CP/M 
3.0 returns an error message. The user recalls the erroneous com- 
mand line by pressing CTRL-W and corrects the error (the underbar 
character represents the cursor): 



A>POPA: = B:*.*_ 
POP? 

A>POPA: = B:V^ 
A>POPA: = B:*.* 
A>POPA: = B:*.* 
A>PP A:=:B:V 
A>pipA: = B:V 



(PIP mistyped) 

(CTRL-W recalls the line) 

(CTRL-B moves cursor to beginning of line) 

(CTRL-F moves cursor to right) 

(CTRL-G deletes error) 

(type I corrects the command name) 



After the command line is corrected, the user can press RETURN 
even though the cursor is in the middle of the line. A RETURN key- 
stroke, (or one of the equivalent control characters) not only exe- 
cutes the command, but also stores the command in a buffer so that 
you can recall it for editing or reexecution by pressing CTRL-W. 

When you insert a character in the middle of a line, characters to the 
right of the cursor move to the right. If the line becomes longer than 
your screen is wide, characters disapper off the right side of the 
screen. These characters are not lost. They reappear if you delete 
characters from the line or if you press CTRL-E when the cursor is in 
the middle of the line. CTRL-E moves all characters to the right of the 
cursor to the next line on the screen. 

Table 13-1 gives a complete list of line-editing control characters for 
the CP/M 3.0 system on the Commodore 128. 

Table 13-1. CP/M 3.0 Line-editing Controi Characters 
Character {Meaning 



CTRL-Aor 
SHIFT-LEFT 
CURSOR 

CTRL-B 



Moves the cursor one character to the left. 



Moves the cursor to the beginning of the com- 
mand line without having any effect on the con- 
tents of the line. If the cursor is at the beginning, 
CTRL-B moves it to the end of the line. 



u 
u 

LJ 
U 

u 



u 






u 
u 
u 
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Table 13-1. CP/M 3.0 Line-editing Control Characters 
(Continued) 



/ 1 



n 



/ I 



I I 



Character 

CTRL-E 



CTRL-F or 
RIGHT 
CURSOR 

CTRL-G 



CTRL-H 



CTRL- 



CTRL-J 



CTRL-K 
CTRL-M 



CTRL-R 



CTRL-U 



CTRL-Wor 
t CRSR i 



Meaning 

Forces a physical carriage return but does not 
send the connnnand line to CP/M 3.0. Moves the 
cursor to the beginning of the next line without 
erasing the previous input. 

Moves the cursor one character to the right. 



Deletes the character at current cursor position. 
The cursor does not nnove. Characters to the 
right of the cursor shift left one place. 

Deletes the character to the left of the cursor 
and moves the cursor left one character posi- 
tion. Characters to the right of the cursor shift 
left one place. 

Moves the cursor to the next tab stop. Tab stops 
are automatically set at each eighth column. 
Has the same effect as pressing the TAB key 

Sends the command line to CP/M 3.0 and 
returns the cursor to the beginning of a new line. 
Has the same effect as a RETURN or a CTRL-M 
keystroke. 

Deletes to the end of the line from the cursor. 

Sends the command line to CP/M 3.0 and 
returns the cursor to the beginning of a new line. 
Has the same effect as a RETURN or a CTRL-J 
keystroke. 

Retypes the command line. Places a # charac- 
ter at the current cursor location, moves the 
cursor to the next line, and retypes any partial 
command you typed so far. 

Discards all the characters in the command line, 
places a # character at the current cursor posi- 
tion, and moves the cursor to the next line. How- 
ever, you can use a CTRL-W to recall any char- 
acters that were to the left of the cursor when 
you pressed CTRL-U. 

Recalls and displays previously entered com- 
mand line both at the operating system level and 
within executing programs, if the CTRL-W is the 
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Table 1 3-1 . CP/M 3.0 Line-editing Control Characters 

(Continued) LJ 

Character Meaning 

first character entered after the prompt. CTRL-J, \ | 

CTRL-M, CTRL-U and RETURN define the com- 
nnand line you can recall. If the comnnand line 

contains characters, CTRL-W nnoves the cursor \ j 

to the end of the connmand line. If you press 
RETURN, CP/M 3.0 executes the recalled 
connnnand. 

CTRL-X Discards all the characters left of the cursor and 

nnoves the cursor to the beginning of the current | ) 

line. CTRL-X saves any characters right of the lJ 



cursor. 
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SECTION 14 
Summary Of 
Major CPm 3.0 
Commands 



THE TWO TYPES OF CP/M 3.0 COMMANDS 
BUILT-IN COMMANDS 
TRANSIENT UTILITY COMMANDS 
REDIRECTING INPUT AND OUTPUT 
ASSIGNING LOGICAL DEVICES 
FINDING PROGRAM FILES 
EXECUTING MULTIPLE COMMANDS 
TERMINATING PROGRAMS 
GETTING HELP 
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As noted in Section 11 , a CP/M 3.0 connnnand line consists of a conn- 
mand keyword, an optional connnnand tail, and a RETURN keystroke. 
This section describes the two kinds of comnnands the connnnand 
keyword can identify and sumnnarizes individual connnnands and 
their functions. The section also gives exannples of some connnnonly 
used comnnands. In addition, the section explains the concept of 
logical and physical devices under CP/M 3.0. This section then tells 
how CP/M 3.0 searches for a program file on a disk, tells how to exe- 
cute multiple commands, and how to reset the disk system. Finally 
the section explains how to use the HELP command to get informa- 
tion on various CP/M topics including command formats and usage, 
right at the keyboard. 



There are two types of commands in CP/M 3.0: 

• Built-in commands — which identify programs in memory 

• Transient utility commands — which identify program files 
on a disk 

CP/M 3.0 has six built-in commands and over 20 transient utility com- 
mands. You can add utilities to your system by purchasing various 
CP/M 3.0-compatible application programs. If you are an experi- 
enced programmer, you can also write your own utilities that operate 
with CP/M 3.0. 



Built-in commands are parts of CP/M 3.0 that are always available 
for your use, regardless of which disk you have in which drive. Built- 
in commands are entered in the computer's memory when CP/M 3.0 
is loaded, and therefore execute more quickly than the transient 
utilities. Table 1 4-1 , on the next page, lists the Commodore 1 28 CP/M 
3.0 built-in commands. 

Some built-in commands have options that require support from a 
related transient utility The related transient utiltiy command has the 
same name as the built-in command and has a f iletype of COM. 
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Transient Utility 
Commands 



Table 14-1. Built-in Commands 

Command Function 

DIR Displays filenames of all files in the directory 

except those marked with the SYS attribute. 

DIRSYS Displays filenames of files marked with the SYS 

(system) attribute in the directory 

ERASE Erases a filename from the disk directory and 

releases the storage space occupied by the file. 

RENAME Renames a disk file. 

TYPE Displays contents of an ASCII (TEXT) file at your 

screen. 

USER Changes to a different user number. 



Some of the major CP/M 3.0 transient utility commands are listed in 
Table 14-2. (The actual list of transient commands may change from 
time to time as the CP/M system is updated or added to.) When you 
enter a command keyword that identifies a transient utility CP/M 3.0 
loads the program file from the disk and passes that file any 
filenames, data or parameters you entered in the command tail. 

HOTE: The built-in commands, DIR, RENAME, and TYPE have 
optional transient extensions. 
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Table 14-2. Transient Utility Commands 
Name Function 
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DATE 
DEVICE 

DIR 

DUMP 
ED 

ERASE 
GENCOM 

GET 

FORMAT 
HELP 

INITDIR 

KEYFIG 
PATCH 

PIP 
PUT 

RENAME 

SAVE 
SET 

SETDEF 

SHOW 

SUBMIT 

TYPE 



Sets or displays the date and time. 

Assigns logical CP/M devices to one or more 
physical devices, changes device driver proto- 
col and baud rates, or sets console screen size. 

Displays directory with files and their character- 
istics. 

Displays a file in ASCII and hexadecimal format. 

Creates and alters ASCII files. 

Used for wildcard erase. 

Creates a special COM file with attached RSX 
file. 

Temporarily gets console input from a disk file 
rather than the keyboard. 

Copies files. 

Displays information on how to use CP/M 3.0 
commands. 

Initializes a disk directory to allow time and date 
stamping. 

Allows redefinition of keys 

Displays or installs patches to CP/M system. 

Copies files and combines files. 

Temporarily directs printer or console output to 
a disk file. 

Changes the name of a file, or a group of files 
using wildcard characters. 

Saves a program in memory to disk. 

Sets file options including disk labels, file attri- 
butes, type of time and date stamping and pass- 
word protection. 

Sets system options including the drive search 
chain. 

Displays disk and drive statistics. 

Automatically executes multiple commands. 

Display contents of text file (or group of files, if 
wildcard characters are used) on screen (and 
printer if desired). 
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CP/M 3.0's PUT command allows you to direct console or printer 
output to a disk file. You can use a GET command to make CP/M 3.0 
or a utility program take console input from a disk file. The following 
examples illustrate some of the capabilities offered by GET and PUT 

You can use a PUT command to direct console output to a disk file 
as well as to the console. With PUT you can create a disk file con- 
taining a directory of all files on that disk, as shown in Figure 1 4-1 . 

A)PUT CONSOLE OUTPUT TO FILE DIR.PRN 
PUTTING CONSOLE OUTPUT TO FILE: DIR.PRN 



A>D/fl 

A: FILENAME 
A: FOUR 
A: TWO 



TEX : FRONT 
TEX : ONE 
TEX : THREE 



TEX : FRONT 
TEX : LINEDIT 
BAK : EXAMP2 



BAK : ONE 
TEX : EXAMP1 
TXT 



AyTYPE DIR.PRN 

A: FILENAME TEX : FRONT TEX : FRONT BAK : ONE 

A: FOUR TEX : ONE TEX : LINEDIT TEX : EXAMPI 

A: TWO TEX : THREE BAK : EXAMP2 TXT 



BAK : THREE 
TXT : TWO 



BAK : THREE 
TXT : TWO 



TEX 
BAK 



TEX 
BAK 



Figure 14-1. PUT Command Example 

A GET connmand can direct CP/M 3.0 or a program to read console 
input from a disk file instead of from the keyboard. If the file is to be 
read by CP/M 3.0, it must contain standard CP/M 3.0 command lines. 
If the file is to be read by a utility program, it must contain input 
appropriate for that program. A file can contain both CP/M 3.0 com- 
mand lines and program input if it also includes a command to start 
a program. 



The minimal Commodore 128 CP/M 3.0 hardware includes a console 
consisting of a keyboard and screen display and a 1571 disk drive. 
You may want to add another device to your system, such as a 
printer or a modem. To help keep track of these physically different 
input and output devices, Table 14-3 gives the names of CP/M 3.0 
logical devices. It also shows the physical devices assigned to these 
logical devices in the Commodore 1 28 CP/M 3.0 system. 
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Executing 

Multipie 

Commands 



Table 14-3. CP/M 3.0 Logical Devices 



Logical 




Physical Device 


Device Name 


Device Type 


Assignment 


CONIN: 


Console input 


Keys 


CONOUT: 


Console output 


80 COL or 40 COL 


AUXIN: 


Auxiliary input 


Null 


AUXOUT: 


Auxiliary output 


Null 


LST: 


List output 


PTR1 or PTR2 



You can change these assignnnents with a DEVICE connnnand. 



If a command keyword identifies a utility CP/M 3.0 looks for that 
program file on the default or specified drive. It looks under the cur- 
rent user number, and then under user for the same file marked 
with the SYS attribute. At any point in the search process, CP/M 3.0 
stops the search if it finds the program file. CP/M 3.0 then loads the 
program into memory and executes it. When the program termi- 
nates, CP/M 3.0 displays the system prompt and waits for your next 
command. However, if CP/M 3.0 does not find the command file, it 
repeats the command line followed by a question mark, and waits for 
your next command. 



In the examples so far, CP/M 3.0 has executed only one command at 
a time. CP/M 3.0 can also execute a sequence of commands. You 
can enter a sequence of commands at the system prompt, or you 
can put a frequently needed sequence of commands in a disk file, 
using a f iletype of SUB. Once you have stored the sequence in a disk 
file, you can execute the sequence whenever you need to with a 
SUBMIT command. 
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You can use the two keystroke command CTRL-C to terminate pro- 
gram execution or reset tine disk system. To enter a CTRL-C com- 
mand, hold down the CTRL key and press C. 

Most application programs that run under CP/M and most CP/M tran- 
sient utilities can be terminated by a CTRL-C. However, if you try to 
terminate a program while it is sending a display to the screen, you 
may need to press a CTRL-S to halt the display before you enter 
CTRL-C. 



CP/M 3.0 includes a transient utility command called HELP that will 
display a summary of the format and use for the most common CP/M 
commands. To access HELP, simply enter the command: 

A)HELP 

You can press the HELP key instead of typing the word HELP and 
pressing the RETURN key 

The list of available topics is then displayed, like this: 
Topics available: 



0128 

DIR 

GET 

LINK 

RMAC 

SUBMIT 



CP/M 



COMMANDS ONTRLCHARS OOPYSYS DATE 

DUMP ED ERASE 

HELP HEXOOM INITDIR 

MAC PATCH PIP<OOPY> PUT 

SAVE SET SETDEF SHOW 

TYPE USER XREF 



DEVICE 
FILESPEC GENCOM 
KEYFIG LIB 

RENAME 

SID 



NOTE: Some of the topics listed are not included with the basic 
CP/M system. These topics are supplied when the user purchases 
the additional CP/M materials, including manuals and disks, by filling 
out the order form preceding page 21 9. 

Suppose you type: 

HELP> PIP 
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CP/M then displays the following infornnation: 

PIP (COPY) 

Syntax: 

DESTINATION SOURCE 

PIP d: {Gn}|filespec {[Gn]} =filespec {[o]} ,..^d: {[o]} 

Explanation: 

The file copy program PIP copies files, combines files, 
and transfers files between disks, printers, consoles, or 
other devices attached to your computer. The first 
filespec is the destination. The second filespec is the 
source. Use two or more source filespecs separated by 
commas to combine two or more files into one file, [o] is 
any combination of the available options. The [Gn] option 
in the destination filespec tells PIP to copy your file to 
that user number. 

PIP with no command tail displays an * prompt and 
awaits your series of commands, entered and processed 
one line at a time. The source or destination can be any 
CP/M 3.0 logical device. 

The HELP facility provides information like this on all the CP/M 3.0 
built-in and transient utility comnnands. If you want information on a 
specific area, you can type HELP subject after the system prompt, 
where subject is a command tail describing the subject you are inter- 
ested in. For example: 

A> HELP PIP 
A> HELP DIRSYS 

You can refer to HELP any time you need information on a specific 
command. Or you can just browse through HELP to broaden your 
knowledge of CP/M 3.0. 
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SECTION 15 
Commodore 
Enhancements To 
CP/M 3.0 



KEYBOARD ENHANCEMENTS 
KEYFIG 
Defining a Key 
Defining a String 
Using ALT Mode 

SCREEN ENHANCEI\AENTS 

MFM DISK FORIMATS 
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Commodore has added a number of enhancements to CP/M 3.0. 
These enhancements tailor the capabilities of the Commodore 128 
to those of CP/M 3.0. They include such things as a selectively dis- 
played disk status line, a virtual disk drive, local/remote handling of 
keyboard codes, programmable function keys (strings), and a num- 
ber of additional functions/characters that are assigned to various 
keys. This section describes these enhancements. 



Any key on the keyboard can be defined to generate a code or func- 
tion, except the following keys: 

Left SHIFT key 
Right SHIFT key 
Commodore key 
CONTROL key 
RESTORE key 
40-80 key 
CAPS LOCK key 

In defining a key the keyboard recognizes the following special func- 
tions. To indicate these functions, hold down the CONTROL key and 
the right SHIFT key and press the desired function key simultane- 
ously 



Key 
CURSOR LEFT key 
CURSOR RIGHT key 

ALT key 



Function 
Defines key 

Defines string (points to function 
keys) 
Toggles key filter 



KEYFIG 

The KEYFIG utility program allows you to alter the definition of 
almost ANY key on the keyboard. The only keys that you CANNOT 
modify are: the SHIFT keys, the SHIFT LOCK key the CONTROL key 
the 40/80 DISPLAY key and the COMMODORE key At each step, 
options are presented in menu form. You can scroll through the 
options in the menus by using the up and down arrow keys at the top 
of the keyboard; pressing the return key selects the choice that is 
highlighted. 

At almost any point, you can exit the program by typing 'CTRL C (the 
CONTROL and C keys simultaneously). 
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Defining A Key 



Left arrow Cursor left 

Right arrow Cursor right 
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A user can define the code that a key can produce. Each key has 

four possible definitions: Normal, Alpha Shift, Shift and Control. The 

Alpha Shift is toggled on/off by pressing the Connnnodore key After U 

entering this nnode, a small box will appear on the bottom of the 

screen. The first key that is pressed is the key to be defined. The 

current HEX (hexadecimal) value assigned to this key is displayed; j { 

the user can then type the new HEX code for the key or abort by 

typing a non-HEX key The following is a definition of the codes that 

can be assigned to a key (In ALT mode, codes are returned to the [^ 

application; see ALT Mode below.) 

Code Function 

OOh Null (same as not pressing a key) 

01 h to 7Fh Normal ASCII codes 

80h to 9Fh String assigned 

AOh to AFh 80-column character color 

BOh to BFh 80-column background color 

COh to CFh 40-column character color i . 

DOh to DFh 40-column background color LJ 

EOh to EFh 40-column border color 

FOh Toggle disk status on/of f | ) 

F1h System Pause ^ — \ 

F2h (Undefined) 

F3h 40-column screen window right 

F4h 40-column screen window left 

FShtoFFh (Undefined) 

Defining A String LJ 

This function allows the user to assign more than one key code to a 

single key Any key that is typed in this mode is placed in the string. ) j 

To access this function, press CTRL, RIGHT SHIFT and RIGHT CUR- ^^ 

SOR. Then press the key to be defined. The user can see the results 

of typing in a box at the bottom of the screen. | ( 

NOTE: Some keys may not display what they are. To provide the user 

with control over the process of entering data, the following five spe- . i 

cial key functions, are available. To access these functions, press ! i 

the CONTROL and right SHIFT keys and the desired function keys. 

Key Function \ ) 

RETURN Complete string definition ^~^ 

+ (on main keyboard) Insert space into string 

- (on main keyboard) Delete cursor character I ( 
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Using ALT Mode 

ALT mode is a toggle function (that is, it can be switdied between 
ON and OFF.) Tlie default value is OFF This function allows the user 
to send 8-bit codes to an application. 



Screen 


The default screen in CP/M 3.0 emulates an ADM31 terminal. The 


Enhancements 


following screen 


functions emulate ADM 3A operation, which is a 


■ 


subset of ADM31 operation. 




CTRLG 


Sound bell 




CTRLH 


Cursor left 




CTRL J 


Cursor down 




CTRLK 


Cursor up 




CTRLL 


Cursor right 




CTRLM 


Move cursor to start of current line (CR) 




CTRLZ 


Home cursor and clear screen 




ESC = RC 


Cursor position where R is the row location (with 
values from space to 8) and C is the column loca 
tion (next values from space to 0), referenced to 
the status line 




Additional functions in ADM31 mode include: 




ESCT) 
ESCt 


Clear to end of line 




ESCY) 


Clear to end of screen 




ESCy ) 






ESC: 1 


Home cursor and clear screen (including the 




ESCM 


status line) 




ESCQ 


Insert character 




ESCW 


Delete character 




ESCE 


Insert line 




ESCR 


Delete line 



* ESC ESC ESC color# sets a screen color from a table of 1 6 
color entries. (These are the same color values listed in Chapter 
II, Section 6, Figure 6-2.) The color # will be set as follows: 

20h to 2Fh physical character color 

30h to 3Fh physical background color 

40h to 4Fh physical border color (40 column only) 

50h to 5Fh logical character color 

60h to 6Fh logical background color 

70h to 7Fh logical border color (40 column only) 

NOTE: Physical and logical colors have the same default values. 
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Formats 



The visual effects associated with following functions are visible only 
with the 80-column screen fornnat. 



ESC> 


Half intensity 


ESC< 


Full intensity 


ESCG4 


Reverse video ON 


ESCG3 


Turn underline ON 


ESCG2 


Blink ON 


ESCG1 


Select the alternate character set 


ESC GO 


All ESC G attributes OFF 
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*NOTE: This is NOT a normal ADM31 sequence. 

For non-Connnnodore CP/M programs you will probably need to spec- 
ify the format of the CP/M program disk. Format in this case refers to 
a particular way of arranging the data on a disk. These disk formats 
(referred to as MFM formats) generally are designed to match the 
specific capabilities of the system for which the particular CP/M 
program was created. 

When used with the fast 1571 disk drive, the Commodore 1 28 sup- 
ports a variety of double density MFM disk formats (for reading and/ 
or writing), including: 

Epson QX1 (512 byte sectors, double sided, 1 sec- 

tors per track) 

IBM-8 SS (CP/M 86) (512 byte sectors, single sided, 8 sectors 
per track) 

IBM-8 DS (CP/M 86) (512 byte sectors, double sided, 8 sectors 
per track) 

KayPro II (512 byte sectors, single sided, 10 sectors 

per track) 

KayPro IV (512 byte sectors, double sided, 1 sec- 

tors per track) 

Osborne DD (1 024 byte sectors, single sided, 5 sectors 

per track) 

When you insert one of these disks into the disk drive and try to 
access it, the system senses the type of disk with respect to the 
number of bytes per sector and the number of sectors per track. If 
the disk format is not unique, a box is displayed near the bottom left 
corner of the screen, showing which disk type you are accessing. 
The system requires you to select the specific disk type by scrolling 
through the choices given in this window. Note: The choices are 
given one at a time; scroll through using the right and left arrow keys. 
Type RETURN when the disk type that you know is in the disk drive is 
displayed. Typing CONTROL RETURN will lock this disk format so 
that you will not need to select the disk type each time you access 
the disk drive. 
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EPSON is a registered trademarl< of EPSON Corp. 

IBM is a registered trademark of International Business 

Machines Corp. 
Kaypro is a registered tradennark of Kay Computers, a division 

of Non-Linear Systems. 
Osborne is a registered trademark of Osborne Computer Corp. 

**••*****•*•*•**•**•*****••••••••******•***•••••****•* 

The sections in this chapter provide a summary of the structure and 
wide-ranging capabilities of CP/I\/1 3.0 For detailed information on any 
facet of CP/I\/1 3.0, you should respond to the offer described on the 
card included in this chapter In return you will receive a copy of the 
Digital Research, Inc. book, CP/M Plus User's Guide. 
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This chapter lists BASIC 7.0 language elements. It gives a complete 
list of the rules (syntax) of Commodore 128 BASIC 7.0, along with a 
concise description of each. 

BASIC 7.0 includes all the elements of BASIC 2.0. The new com- 
mands, statements, functions and operators provided in BASIC 7.0 
are highlighted in color. 

The different types of BASIC operations are listed in individual sec- 
tions, as follows: 

1 . COMMANDS and STATEMENTS: the commands used to 
edit, store and erase programs; and the BASIC program 
statements used in the numbered lines of a program. 

2. FUNCTIONS: the string, numeric and print functions. 

3. VARIABLES AND OPERATORS: the different types of vari- 
ables, legal variable names, arithmetic operators and logical 
operators. 

4. RESERVED WORDS AND SYMBOLS: the words and sym 
bols reserved for use the BASIC 7.0 language, which cannot 
be used for any other purpose. 



The commands and statements definition in this encyclopedia are 
arranged in the following format: 



Command name-^ 

Brief definition-* 

Command format-* 

Discussion of 
format and use-* 



Example(s)^ 



AUTO 

— Enable/disable automatic line numbering 

AUTO[llne#] 

Tliis command turns on the automatic line-numbering fea- 
ture. This eases the job of entering programs, by automati- 
cally typing the line numbers for the user. As each program 
line is entered by pressing RETURN, the next line number is 
printed on the screen, and the cursor is positioned two 
spaces to the right of the line number. The line number 
argument refers to the desired increment between line 
numbers. AUTO without an argument turns off the auto line 
numbering, as does RUN. This statement can be used only 
in direct mode (outside of a program). 

EXAMPLES: 

AUT0 10 Automatically numbers program lines in 
increments of 10. 

AUTO 50 Automatically numbers lines in increments 
of 50. 

AUTO Turns off automatic line numbering. 
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The boldface line that defines the format consists of the following 
elements: 

DLOAD "program name" [,D0,U8] 
t t t 

keyword argument additional arguments 

(possibiy optional) 

The parts of the command or statement that must be typed exactly 
as shown are in capital letters. Words the user supplies, such as the 
name of a program, are not capitalized. 

When quote marks (" ") appear (usually around a program name or 
filename), the user should include them in the appropriate place, 
according to the format example. 

KEYWORDS, also called reserved words, appear in upper-case 
letters. Keywords are words that are part of the BASIC language. 
They are the central part of a command or statement, and they tell 
the computer what kind of action to take. These words cannot be 
used as variable names. A complete list of reserved words and sym- 
bols is given in Section 20. 

Keywords may be typed using the full word or the approved abbrevi- ^/ 

ation. (A full list of abbreviations is given in Appendix K). The keyword 
or abbreviation must be entered correctly or an error will result. The 

BASIC and DOS error messages are defined in Appendices A and B, \ j 

respectively 



u 



ARGUMENTS, also called parameters, appear in lower-case letters. 

Arguments complement keywords by providing specific information 

to the command or statement. For example, the keyword load tells 

the computer to load a program while the argument tells the com- ^ j 

puter which specific program to load. A second argument specifies ^ — ' 

from which drive to load the program. Arguments include filenames, 

variables, line numbers, etc. \ [ 

SQUARE BRACKETS [\ show optional arguments. The user selects 

any or none of the arguments listed, depending on requirements. ^ | 

ANGLE BRACKETS < > indicate the user MUST choose one of the 

arguments listed. \ \ 
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A VERTICAL BAR | separates items in a list of arguments when the 
choices are limited to those arguments listed. When the vertical bar 
appears in a list enclosed in SQUARE BRACKETS, the choices are 
limited to the items in the list, but the user still has the option not to 
use any arguments. If a vertical bar appears within angle brackets, 
the user must choose one of the listed arguments. 

ELLIPSIS ... a sequence of three dots means an option or argu- 
ment can be repeated more than once. 

QUOTATION MARKS " " enclose character strings, filenames and 
other expressions. When arguments are enclosed in quotation 
marks, the quotation marks must be included in the command or 
statement. Quotation marks are not conventions used to describe 
formats; they are required parts of a command or statement. 

PARENTHESES When arguments are enclosed in parentheses, 
they must be included in the command or statement. Parentheses 
are not conventions used to describe formats; they are required 
parts of a command or statement. 

VARIABLE refers to any valid BASIC variable names, such as X, A$, 
T%,etc. 

EXPRESSION refers to any valid BASIC expressions, such as 
A+B + 2,.5*(X + 3).etc. 
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SECTION 17 
BASIC Commands 
and Statements 
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— Append data to the end of a sequential file. 

APPEND #logical file number,"f ilename"[,Ddrive number] 
[<ON|,>Udevice] 

This comnnand opens the file having the specified filename, and 
positions the pointer at the end of the file. Subsequent PRINT* 
(write) statements will cause data to be appended to the end of this 
logical file number. Default values for drive number and device num- 
ber are and 8 respectively. 

Variables or expressions used as filenames must be enclosed within 
parentheses. 



EXAMPLES: Append # 8, ''MYFILE" 



Append # 7, (A$),D0,U9 



OPEN logical file 8 
called "MYFILE" for 
appending with 
subsequent PRINT* 
statements. 

OPEN logical file 
named by the 
variable in A$ on 
drive 0, device 
number 9, and 
prepare to APPEND. 



— Enable/disable automatic line numbering 

AUTO[line#] 

This command turns on the automatic line-numbering feature. This 
eases the job of entering programs, by automatically typing the line 
numbers for the user. As each program line is entered by pressing 
RETURN, the next line number is printed on the screen, and the cur- 
sor is positioned two spaces to the right of the line number. The line 
number argument refers to the desired increment between line num- 
bers. AUTO without an argument turns off the auto line numbering, 
as does RUN. This statement can be used only in direct mode (out- 
side of a program). 
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BACKUP 



BANK 



EXAMPLES: 

AUTO 10 Automatically numbers program lines in increments of 10. 
AUTO 50 Automatically numbers lines in increments of 50. 
AUTO Turns off automatic line numbering. 



— Copy the entire contents f ronn one disk to another on a dual disk 
drive 

BACKUP source Ddrive number TO destination Ddrive 
number [<ON | ,>Udevice] 

This connnnand copies all the files f ronn the source diskette onto the 
destination diskette, using a dual disk drive. With the BACKUP conn- 
nnand, a new destination diskette can be used without first fornnat- 
ting it. This is because the BACKUP connnnand copies all the infor- 
mation on the diskette, including the fornnat, and destroys any 
infornnation already on the destination disk. Therefore, when backing 
up onto a previously used diskette, nnake sure it contains no pro- 
granns you mean to keep. As a precaution the computer asks "ARE 
YOU SURE?" before it starts the operation. Press the "Y" key to 
perform the BACKUP, or any other key to stop it. You should always 
create a backup of all your disks, in case the original diskette is lost 
or damaged. Also see the COPY command. The default device num- 
ber is unit 8. 

NOTE: This command can be used only with a dual-disk drive. 

EXAMPLES: 

BACKUP DO to D1 Copies all files from the disk in drive 

to the disk in drive 1, in dual disk 
drive unit 8. 



BACKUP DO TO D1 ON U9 



Copies all files from drive to drive 
1, in disk drive unit 9. 
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—Select one of the 16 BASIC banks (default memory configura- 
tions), numbered 0-15 

BANK bank number 

This statement specifies the bank number and corresponding mem- 
ory configuration for the Commodore 128 memory The default bank 
is 15. Here is a table of available BANK configurations in the Commo- 
dore 128 memory: 
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BANK 



1 

2 

3 

4 

5 

6 

7 

8 

9 
10 
11 
12 
13 
14 
15 



CONFIGURATION 



RAM(0) only 
RAM(1) only 
RAM(2) only 
RAM(3) only 
Internal ROM 
Internal ROM 
Internal ROM 
Internal ROM 
External ROM 
External ROM 
External ROM 
External ROM 



RAM(0), I/O 

RAM(1), I/O 

RAM(2), I/O 

RAM(3), I/O 

RAM(0), I/O 

RAM(1), I/O 

RAM(2), I/O 

RAM(3), I/O 
Kernel and Internal ROM (LOW), RAM(0), I/O 
Kernel and External ROM (LOW), RAM(1), I/O 
Kernel and BASIC ROM, RAM(0), Character ROM 
Kernel and BASIC ROM, RAM(0), I/O 



To look at a particular bank, type BANK n (n = 0-15). 

To access these banks within the machine language monitor, pre- 
cede the four-digit hexadecimal number of the address range you 
are viewing with a hexadecimal digit (0-F). 

Banks are described in detail in the Commodore 128 Program- 
mer's Reference Guide, published by Bantam Books. 



BEGINIBEND 



A conditional statement like IF. . . THEN: ELSE, structured so that 
you can include several program lines between the start (BEGIN) 
and end (BEND) of the structure. Here's the format: 

IF Condition THEN BEGIN : statement 

statement 

statement BEND : ELSE BEGIN 

statement 

statement BEND 
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BLOAD 



For EXAMPLE: 

10 IF X = 1 THEN BEGIN: PRINT "X = 1 is True" 

20 PRINT "So this part of the statement is performed" 

30 PRINT "When X equals 1" 

40 BEND: PRINT "End of BEGIN/BEND structure":GO to 60 

50 PRINT "X does not equal 1":PRINT "The statements 

between BEGIN/BEND are skipped" 

60 PRINT "Rest of Program" 

If the conditional (IR.THEN) statement in line 10 is true, the state- 
nnents between the keywords BEGIN and BEND are performed, 
including all the statements on the same line as BEND. If the 
(IR.THEN) conditional statement in line 10 is FALSE, all statements 
between the BEGIN and BEND, including the ones on the same pro- 
gram line as BEND are skipped, and the program resumes with the 
first program line immediately following the line containing BEND. 
The BEGIN/BEND essentially treats lines 10 through 40 as one long 
line. 

The same rules are true if the ELSE:BEGIN clause is specified. If the 
condition is true, all statements between ELSE:BEGIN and BEND 
are performed, including all statements on the same line as BEND. If 
false, the program resumes with the line immediately following the 
line containing BEND. 



— Load a binary file starting at the specified memory location 

BLOAD "filename"[,Dclrive number][,Udevice number] 
[,Bbank number][,Pstart address] 

where: 

• filename is the name of your file 

• bank number lets you select one of the 16 BASIC banks 

• start address is the memory location where loading 
begins 

A binary file is a file, whether a program or data, that has been 
SAVEd either within the machine language monitor or by the BSAVE 
command. The BLOAD command loads the binary file into the loca- 
tion specified by the start address. 



EXAMPLES: 

BLOAD "SPRITES", BO, P3584 



LOADS the binary file 
"SPRITES" starting in 
location 3584 (in BANK 0). 
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BOOT 



BOX 



BLOAD "DATA1", DO, U8, B1, P4096 LOADS the binary file 

"DATA 1" into location 4096 
(BANKI)fronn Drive 0, 
unit 8. 



— Load and execute a progrann which was saved as a binary file 

BOOT "filename" [,Dclrive number][<ON | ,>Udevice] 

The comnnand loads an executable binary file and begins execution 
at the predefined starting address. The default device number is 8 
(drive 0). 

EXAMPLE: 

BOOT BOOT a bootable disk (CP/M Plus for 

example). 

BOOT "GRAPHICS 1", LOADS the binary program 

DO, U9 "GRAPHICS 1" from unit 9, drive 0, 

and executes it. 

— Draw box at specified position on screen 

BOX [color source], XI , Y1[,X2,Y2][,[angle][,paint]] 

where: 

color source = Background color 

1 = Foreground color 

2 = Multicolor 1 

3 = Multicolor 2 

x1, y1 Top left corner coordinate (scaled) 

x2, y2 Bottom right corner opposite x1 , y1 , 

(scaled); default is the PC location. 

angle Rotation in clockwise degrees; 

default is degrees 

paint Paint shape with color 

= Do not print 

1 = Paint 
(default = 0) 

This statennent allows the user to draw a rectangle of any size on the 
screen. Rotation is based on the center of the rectangle. The pixel 
cursor (PC) is located at x2, y2 after the BOX statement is executed. 
The color source number must be a zero (0) or one (1) if in standard 



n 
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bit map mode, or a 2 or 3 if in multicolor bit map mode. Also see the 
GRAPHIC command for selecting the appropriate graphic mode to 
be used with the BOX color source number. 

The X and y values can place the pixel cursor at absolute coordi- 
nates such as (100,100) or at coordinates relative to previous posi- 
tion ( + / - X and + / - y) of the pixel cursor such as ( + 20, - 1 0). The 
coordinate of one axis (x or y) can be relative and the other can be 
absolute. Here are the possible combinations of ways to specify the 
X and y coordinates: 



x,y 

+/-x,y 
x,+/-y 
+ /-x,+/-y 



absolute x, absolute y 
relative x, absolute y 
absolute x, relative y 
relative x, relative y 



Also see the LOCATE command for information on the pixel cursor. 

The graphics commands DRAW, BOX, CIRCLE, PAINT LOCATE and 
GSHAPE have an additional notation which allows you to specify a 
distance and an angle relative to the previous coordinates of the 
pixel cursor (PC). The notation is as follows: 



KEYWORD 

where: 

KEYWORD 

SOURCE 



source, distance; angle 



is a graphics command such as DRAW, CIRCLE, 
PAINT LOCATE, BOX or GSHAPE 

is the same code as in all of the graphics 
commands 

is the number of pixels to move the pixel cursor 

is the number of degrees to move relative to the 
previous pixel cursor coordinate 



DISTANCE 
ANGLE 

EXAMPLE: 
BOX 1, 100; 90 

displays a BOX in the foreground color, 100 pixels away from and 90 
degrees relative to the previous pixel cursor coordinate The angle is 
calculated as follows: 

(360^) 



270° PC (90*») 
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180° 
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EXAMPLES: 

BOX 1, + 10, + 10 Draw a box 10 pixels to the right and 

10 down from the current pixel cursor 
location. 

BOX 1, 10, 10, 60, 60 Draws the outline of a rectangle. 

BOX , 10, 10, 60, 60, 45, 1 Draws a painted, rotated box (a 

diamond). 

BOX , 30, 90, , 45, 1 Draws a filled, rotated polygon. 

Any paranneter can be omitted but you nnust include a connnna in its 
place, as in the last two examples. 

NOTE: Wrapping occurs if the degree is greater than 360. 



BSAVE 



n 

n 
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— Save a binary file from the specified memory locations 

BSAVE <'f ilename"[,Dclrive number][,Udevice number] 

[iBbank number],Pstart address TO Pend address 

where: 

• filename is the name you give the file 

• drive number is either or 1 on a dual drive (0 is the default 
for a single drive) 

• device number is the number of disk drive unit (default is 8) 

• bank number is the number of the BASIC bank you specify 
(0-15) 

• start address is the starting address where the program is 
SAVEdfrom 

• end address is the last address + 1 in memory which is 
SAVEd 

This is similar to the SAVE command in the Machine Language 
Monitor. 

EXAMPLES: 

BSAVE "SPRITE DATA",B0,P3584 TO P4096 Saves the binary file 

named "SPRITE 
DATA", starting at 
location 3584 through 
4095 (BANK 0). 
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CATALOG 



CHAR 



BSAVE "PROGRAM.SCR",D0,U9,B0,P3182 TO P7999 

Saves the binary 
file named 
"PROGRAM.SCR" in 
tlie mennory address 
range 3182 through 
7999 (BANK 0) on 
drive 0, unit 9. 



— Display the disk directory 

CATALOG [Ddrive number][<ON | ,>Udevice 
number][,wildcard string] 

The CATALOG connnnand displays the directory on the specified 
drive, just like the DIRECTORY connnnand. See the DIRECTORY 
comnnand. 



EXAMPLE: 
CATALOG 



Displays the disk directory on drive 0. 



—Display characters at the specified position on the screen 

CHAR [color source ],x,y[,string][,RVS] 

This is primarily designed to display characters on a bit nnapped 
screen, but it can also be used on a text screen. Here's what the 
parameters mean: 

color source = Background 

1 = Foreground 

X Character column (0-79) 

(wraps around to the next line in 40- 
column mode) 

y Character row (0-24) 

string String to print 

reverse Reverse field flag (0 = off, 1 = on) 

Text (alphanumeric strings) can be displayed on the screen at a given 
location by the CHAR statement. Character data is read from the 
Commodore 128 character ROM. The user supplies the x and y coor- 
dinates of the starting position and the text string to be displayed. 
Color source and reverse imaging are optional. 
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CIRCLE 



In 40-colunnn format the string is continued on the next line if it 
attempts to print past the (40th column) right edge of the screen. 
When used in TEXT mode, the string printed by the CHAR command 
works just like a PRINT command, including cursor and color control. 
These control functions inside the string do not work when the CHAR 
command is used to display text in bit map mode. Upper/lower case 
controls (CHR$ (14) or CHR$ (142)) also operate in bit map mode. 

Multicolor characters are handled differently than standard charac- 
ters. First select multicolorl and multicolor 2 with the COLOR com- 
mand. Set the GRAPHIC mode to multicolor. To display the fore- 
ground on multicolor 1 , set the color source in the CHAR command 
to zero and the reverse flag to zero. To display the foreground on 
multicolor 2, set the color source to and the reverse flag to 1 . The 
following example displays the foreground character color using a 
red background. Change the reverse flag to 1 and the characters are 
displayed in multicolor 2 (blue). 

10 Color 2,3: REM multicolor 1 = Red 
20 Color 3,7: REM multicolor 2 = Blue 
30 GRAPHIC 3,1 
30 CHAR 0,10,10,"TEXT",0 

— Draw circles, ellipses, arcs, etc. at specified positions on the 
screen 

CIRCLE [color source],X,Y[,Xr][,Yr] 
[,sa][,ea][,angle][,inc] 



where: 



color source = background color 

1 = foreground color 

2 = multicolor 1 

3 = multicolor 2 

x,y Center coordinate of the CIRCLE 

xr X radius (scaled) 

yr Y radius (default is xr) 

sa Starting arc angle (default degrees) 

ea Ending arc angle (default 360 degrees) 

angle Rotation is clockwise degrees (default 

is degrees) 

Inc Degrees between segments (default is 

2 degrees) 



n 
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With the CIRCLE statement, the user can draw a circle, ellipse, arc, 
triangle, octagon or other polygon. The pixel cursor (PC) is left at the 
circumference of the circle at the ending arc angle. Any rotation is 
relative to the center. Setting the y radius equal to the x radius does 
not draw a perfect circle, since the x and y coordinates are scaled 
differently (x = -320 and y = -200). Arcs are drawn from the 
starting angle clockwise to the ending angle. The increment controls 
the smoothness of the shape; using lower values results in more 
nearly circular shapes. Specifying the inc greater than 2 creates a 
rough-edged, boxed-in shape. 

The X and y values can place the pixel cursor at absolute coordi- 
nates such as (100,100) or at coordinates relative to the previous 
position ( + / - X and 4- / - y) of the pixel cursor such as ( H- 20, - 1 0). 
The coordinate of one axis (x or y) can be relative and the other can 
be absolute. Here are the possible combinations of ways to specify 
the X and y coordinates: 

x,y absolute x, absolute y 

+ / - x,y relative x, absolute y 

X, + / - y absolute x, relative y 

+ / - X, + / - y relative x, relative y 

Also see the LOCATE command for information on the pixel cursor. 

The graphics commands DRAW, BOX, CIRCLE, RMNT LOCATE AND 
GSHAPE have an additional notation which allows you to specify a 
distance and an angle relative to the previous coordinates of the 
pixel cursor (PC). The notation is as follows: 



KEYWORD 

where: 

KEYWORD 

SOURCE 

DISTANCE 



source, distance; angle 



is a graphics command such as DRAW, 
CIRCLE, RMNT LOCATE, BOX or GSHAPE 

is the same code as in all of the graphics 
commands 

is the number of pixels to move the pixel 
cursor 
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CLOSE 



CLR 



CMD 



ANGLE is the number of degrees to move relative to 

tlie previous pixel cursor coordinate 



EXAMPLES: 
CIRCLE1, 160,100,65,10 
CIRCLE1, 160,100,65,50 
CIRCLE1, 60,40,20,18„„45 
CIRCLE1, 260,40,20„,„90 



Draws an ellipse. 
Draws a circle. 
Draws an octagon. 
Draws a diamond. 



CIRCLE1, 60,140,20,18„„120 Draws a triangle. 



CIRCLE 1, + 2, + 2,50,50 



Draws a circle (two pixels down and 
two to the right) relative to the 
original coordinates of the pixel 
cursor. 



You nnay omit a parameter, but you must still place a comma in the 
appropriate position. Omitted parameters take on the default values. 



— Close logical file 

CLOSE file number 

This statement closes any files used by the DOPEN or OPEN state- 
ments. The number following the word CLOSE is the file number to 
be closed. 



EXAMPLE: 
CLOSE 2 



Logical file 2 is closed. 
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— Clear program variables 

CLR 

This statement erases any variables in memory but leaves the pro- 
gram intact. This statement is automatically executed when a RUN 
or NEW command is given. There is no need to use CLR after edit- 
ing, because variables and text no longer share memory 



— Redirect screen output 

CMD logical file number [,wrlte list] 

This command sends the output, which normally goes to the screen 
(i.e., PRINT statement, LIST but not POKES into the screen) to 
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COLLECT 



COLLISION 
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another device, such as a disk data file or printer. This device or file 
must be OPENed first. The CMD command must be followed by a 
number or numeric variable referring to the file. The write list can be 
any alphanumeric string or variable. This command is useful for 
printing headings at the top of program listings. 



EXAMPLE: 
Open 1,4 
CMD1 
LIST 

PRINT#1 
CLOSE 1 



OPENS device #4, which is the printer. 

All normal output now goes to the printer. 

The LISTing goes to the printer, not the 
screen — even the word READY 

Sends output back to the screen. 

Closes the file. 



— Free inaccessible disk space 

COLLECT [Ddrive number][<ON | ,>Udevice] 

Use this command to make available any disk space that has been 
allocated to improperly closed (splat) files, and to delete references 
to these files from the directory Splat files are files that appear on 
the directory with an asterisk next to them. Defaults to device 
number 8. 



EXAMPLE: 
COLLECT DO 



Free all available space which has been 
incorrectly allocated to improperly closed 
files. 



— Define handling for sprite collision interrupt 
COLLISION type [,statement] 



type. 



statement 



.Type of interrupt, as follows: 

1 = Sprite-to-sprite collision 

2 = Sprite-to-display data collision 

3 = Light pen 

.BASIC line number of a subroutine 



When the specified situation occurs, BASIC will finish processing 
the currently executing instruction and perform a GOSUB to the line 
number given. When the subroutine terminates (it must end with a 
RETURN), BASIC will resume processing where it left off. Interrupt 
action continues until a COLLISION of the same type without a line 
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COLOR 



number is specified. More than one type of interrupt may be enabled 
at the same time, but only one interrupt can be handled at a time 
(i.e., there can be no recursion and no nesting of interrupts). The 
cause of an interrupt may continue causing interrupts for some time 
unless the situation is altered or the interrupt disabled. 

When a sprite is completely off-screen and not visible, it cannot gen- 
erate an interrupt. To determine which sprites have collided since 
the last check, use the BUMP function. 



EXAMPLE: 
Collision 1, 5000 

Collision 1 
Collision 2, 1000 



Detects a sprite-to-sprite collision 
and program control sent to 
subroutine at line 5000. 

Stops interupt action which was 
initiated in above example. 

Detects sprite-to-data collision and 
program control directed to 
subroutine in line 1000. 



— Define colors for each screen area 
COLOR source number, color number 

This statement assigns a color to one of the seven color areas: 
Area Source 




1 
2 
3 
4 
5 
6 



40-column (VIC) background 

40-column (VIC) foreground 

multicolor 1 

multicolor 2 

40-column (VIC) border 

character color (40- or 80-column screen) 

80-column background color 



Colors that are usable are in the range 1 -1 6. 



Color Code 
1 
2 
3 
4 
5 
6 
7 
8 



Color 

Black 

White 

Red 

Cyan 

Purple 

Green 

Blue 

Yellow 



Color Code 
9 
10 
11 
12 
13 
14 
15 
16 



Color 



Orange 
Brown 
Light Red 
Daric Gray 
Medium Gray 
Light Green 
Light Blue 
Light Gray 



Color Numbers in 40-Column Output 
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2 
3 
4 
5 
6 
7 
8 


Black 
White 
Dark Red 
Light Cyan 
Light Purple 
Dark Green 
Dark Blue 
Light Yellow 


9 
10 
11 
12 
13 
14 
15 
16 


Dark Purple 
Dark Yellow 
Light Red 
Dark Cyan 
Medium Gray 
Light Green 
Light Blue 
Light Gray 


Color Numbers in 


80-Column Output 


EXAMPLE: 








Color 0, 1: 




Changes background color of 40- 
column screen to black. 



u 



\ ) 



u 



S J 



Color 5, 8: 



Changes character color to yellow. 



CONCAT 



—Concatenate two data files 

CONCAT "file 2" [,Dclrive number] TO "file 1 " 
[,Ddrive number][<ON | ,>Udevice] 

The CONCAT comnnand attaches file 2 to the end of file 1 and retains 
the name of file 1 . The device nunnber defaults to 8 and the drive 
number defaults to 0. 



EXAMPLE: 
Concat "File B' 



to "File A" 



Concat (A$) to (B$), D1, U9 



FILE B is attached to FILE A, and 
the connbined file is designated 
FILE A. 

The file nanned by B$ becomes a 
new file with the same name with 
the file named by A$ attached to 
the end of B$— This is performed on 
Unit 9, drive 1 (a dual disk drive). 

Whenever a variable is used as a filename, as in the last example, 
the filename variable must be within parentheses. 



CdNT 



— Continue program execution 
CONT 

This command is used to restart a program that has been stopped 
by either using the STOP key, a STOP statement, or an END state- 
ment. The program resumes execution where it left off. CONT will 
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not resume with the program if lines have been changed or added to 
the program or if any editing of the program is performed on the 
screen. If the program stopped due to an error; or if you have caused 
an error before trying to restart the program, CONT will not work. 
The error message in this case is CANT CONTINUE ERROR. 



COPY 



— Copy files from one drive to another in a dual disk drive, or within a 
single drive 

COPY [Ddrive number,]"source f ilename"TO"clestination 
filename"[,Dclrive number][<ON | ,>Uclevlce] 

This command copies files from one disk (the source file) to another 
(the destination file) on a dual-disk drive. It can also create a copy of 
a file on the same disk within a single drive, but the filename must be 
different. When copying from one drive to another, the filename may 
be the same. 

The COPY command can also COPY all the files from one drive to 
another on a dual disk drive. In this case the drive numbers are spec- 
ified and the source and destination filenames are omitted. 

The default parameters for the COPY command are device number 
8. drive 0. 

NOTE: Copying between two single or double disk drive units cannot 
be done. This command does not support unit-to-unit copying. See 
BACKUP 

EXAMPLES: 

COPY DO, "test" TO D1, "test prog" Copies "test" from drive 

to drive 1 , renaming it 
"test prog" on drive 1. 

COPY DO, "STUFF" TO D1, "STUFF" Copies "STUFF" from 

drive to drive 1 . 



COPY DO to D1 



Copies all files from drive 
to drive 1 . 



COPY "WORK.PROG" TO "BACKUP" Copies "WORK.PROG" as 

a file called "BACKUP" on 
the same disk (drive 0). 
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DATA 



— Define data to be used by a program 

DATA list of constants 

This statement is followed by a list of data items to be input into the 
computer's memory by READ statements. The items may be 
numeric or string and are separated by commas. String data need 
not be inside quote marks, unless they contain any of the following 
characters: space, colon, or comma. If two commas have nothing 
between them, the value is READ as a zero if numeric, or as an 
empty string. Also see the RESTORE statement, which allows the 
Commodore 128 to reread data. 

EXAMPLE: 

DATA 100, 200, FRED, "HELLO, MOM", , 3, 14, ABC123 



u 
u 

Li 
U 

( 1 

U 



DCLEAR 



— Clear all open channels on disk drive 

DCLEAR [Ddrive number][<ON | ,>Udevlce] 

This statement closes all files and clears all open channels on the 
specified device number. Default is DO, U8. This command is analag- 
ous to OPEN 10,8,15, "IO":CLOSE 10. 

EXAMPLES: 



DCLEAR DO 



DCLEAR D1,U9 



Clears all open files on drive 0, 
device number 8. 

Clears all open files (channels) on 
drive 1 , device number 9. 



u 



u 
u 



DCLOSE 
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— Close disk file 

DCLOSE [#logical file number][<ON | ,>Uclevice] 

This statement closes a single file or all the files currently open on 
a disk unit. If no logical file number is specified, all currently open 
files are closed. The default device number is 8. Note the following 
examples: 



EXAMPLES: 
DCLOSE 
DCLOSE #2 

DCLOSE ON U9 



Closes all files currently open on unit 8. 

Closes the file associated with the logical file 
number on unit 8. 

Closes all files currently open on unit 9. 
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DEFFN 



n 
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DELETE 



I 1 



n 



n 

i \ 



DIM 



— Return the value of a user-defined function 

DEF FN name (variable) = expression 

This statennent allows the definition of a complex calculation as a 
function. In the case of a long fornnula that is used several times 
within a program, this keyword can save valuable program space. 
The name given to the function begins with the letters FN, followed 
by any alphanumeric name beginning with a letter. First, define the 
function by using the statement DEF, followed by the name given to 
the function. Following the name is a set of parentheses () with a 
dummy numeric variable name (in this case, X) enclosed. Next is an 
equal sign, followed by the formula to be defined. The function can 
be performed by substituting any number for X, using the format 
shown in line 20 of the example below: 

EXAMPLE: 

10 DEF FNA(X) = 12*(34.75-X/.3) + X 
20 PRINT FNA(7) 

The number 7 is inserted each place X is located in the formula 
given in the DEF statement. In the example above, the answer 
returned is 144. (Function definitions are lost if BASIC is moved — 
e.g., from $1C(Z)0 to $4000 when a GRAPHIC call occurs. Invoke a 
graphic mode once before defining functions.) 

— Delete lines of a BASIC program in the specified range 

DELETE [first line] [-last line] 

This command can be executed only in direct mode. 
EXAMPLES: 

Deletes line 75. 

Deletes lines 10 through 50, inclusive. 



DELETE 75 
DELETE 10-50 
DELETE-50 



DELETE 75- 



Deletes all lines from the beginning of the 
program up to and including line 50. 

Deletes all lines from 75 to the end of the 
program, inclusive. 



— Declare number of elements in an array 

DIM variable (subscripts) [,varlable(subscrlpts)] . . . 

Before arrays of variables can be used, the program must first exe- 
cute a DIM statement to establish DIMensions of the array (unless 
there are 1 1 or fewer elements in the array). The DIM statement is 
followed by the name of the array which may be any legal variable 



n 
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DIRECTORY 



name. Then, enclosed in parentheses, put the number (or numeric 
variable) of elements in each dimension. An array with more than 
one dimension is called a matrix. Any number of dimensions may be 
used, but keep in mind the whole list of variables being created takes 
up space in memory and it is easy to run out of memory if too many 
are used. Here's how to calculate the amount of memory used by an 
array: 

5 bytes for the array name 
2 bytes for each dimension 

2 bytes/elements for integer variables 

5 bytes/elements for normal numeric variables 

3 bytes/elements for string variables 

1 byte for each character in each string element 

Integer arrays take up two-fifths the space of floating-point arrays 
(e.g., DIM A% (100) requires 209 bytes; DIM A (100) requires 512 
bytes.) 

More than one array can be dimensioned in a DIM statement by sep- 
arating the array variable name by commas. If the program executes 
a DIM statement for any array more than once, the message 
"RE'DIMed ARRAY ERROR" is posted. It is good programming prac- 
tice to place DIM statements near the beginning of the program. 

EXAMPLE: 

10 DIM A$(40),B7(15),CC%(4,4,4) 

Dimensions three arrays, where arrays AH, B7, and CC% have, 
respectively 41 elements, 16 elements and 125 elements 

— Display the contents of the disk directory on the screen 

DIRECTORY [Ddrive number][,<ON | ,) Udevice][,wildcard] 

The F3 function key in CI 28 mode displays the DIRECTORY for 
device number 8, drive 0. Use CONTROL S or NO SCROLL to pause 
the display; any key restarts the display after a pause. Use the COM- 
MODORE key to slow down the display The DIRECTORY command 
cannot be used to print a hard copy The disk directory must be 
loaded (L0AD"$",8) destroying the program currently in memory in 
order to print a hard copy The default device number is 8, and the 
default drive number is 0. 



EXAMPLES: 
DIRECTORY 

DIRECTORY D1, U9, "work" Lists the file named "work," on 

drive 1 of unit 9. 



Lists all files on the disk in unit 8. 



u 
u 



u 
u 
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DLOAD 



DIRECTORY "AB*" Lists all files starting with the letters 

"AB" like ABOVE, ABOARD, etc. on 
all drives of unit 8. The asterisk 
specifies a wild card, where all files 
starting with 'AB" are displayed. 

DIRECTORY DO, "file ?.BAK" The ? is a wild card that nnatches 

any single character in that position. 
For example: file 1.BAK, file 2.BAK, 
file 3.BAK all nnatch the string. 

DIRECTORY D1,U9,(A$) LISTS the filenanne stored in the 

variable A$ on device nunnber 9, 
drive 1 . Rennember, whenever a 
variable is used as a filename, put 
the variable in parentheses. 

NOTE: To print the DIRECTORY of the disk in drive 0, unit 8, use the 
following exannple: 

LOAD"$0",8 

OPEN4,4:CMD4:LIST 

PRINT#4:CLOSE4 



— Load a BASIC program f ronn disk 

DLOAD "filename" [,Ddrive number][,Udevice number] 

This connnnand loads a BASIC progrann fronn disk into current nnenn- 
ory. (Use LOAD to load progranns fronn tape.) The progrann nnust be 
specified by a filenanne of up to 16 characters. DLOAD assumes 
device number 8, drive 0. 



EXAMPLES: 

DLOAD "BANKRECS" 



DLOAD (A$) 



Searches the disk for the progrann 
"BANKRECS" and LOADs it. 

LOADS fronn disk a program whose 
nanne is stored in the variable A$. 
An error nnessage is given if A$ is 
ennpty. Rennennber, when a variable 
is used as a filenanne, it must be 
enclosed in parentheses. 

The DLOAD command can be used within a BASIC program to find 
another program on disk. This is called chaining. 
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— Define and control a progrann loop 

DO [UNTIL condition / WHILE condition] statements [EXIT] 
LOOP [UNTIL condition / WHILE condition] 

This loop structure perfornns the statennents between the DO state- 
nnent and the LOOP statennent. If no UNTIL or WHILE nnodifies either 
the DO or the LOOP statement, execution of the statennents in 
between continues indefinitely. If an EXIT statement is encountered 
in the body of a DO loop, execution is transferred to the first state- 
ment following the LOOP statement. DO loops may be nested, follow- 
ing the rules defined by the FOR-NEXT structure. If the UNTIL 
parameter is specified, the program continues looping until the con- 
dition is satisfied (becomes true). The WHILE parameter is basically 
the opposite of the UNTIL parameter: the program continues looping 
as long as the condition is TRUE. As soon as the condition is no 
longer true, program control resumes with the statement immedi- 
ately following the LOOP statement. An example of a condition (bool- 
ean argument) is A = 1 , or G>65. 



u 



This example performs the statements 
X = X-1 and PRINT "X=";X until X = 0. 
When X = the program resumes with 
the PRINT "End of Loop" statement 
immediately following LOOP 



EXAMPLE: 

10X = 25 

20 DO UNTIL X = 

30X = X-1 

40 PRINT "X = ";X 

50 LOOP 

60 PRINT "End of Loop" 

10 DO WHILE A$<> CHR$ (13):GETKEY A$:PRINT A$:LOOP 
20 PRINT "THE RETURN KEY HAS BEEN PRESSED" 

This DO loop waits for a key to be 
pressed, receives input from the 
keyboard one character at a time and 
prints the letter of the key which was 
pressed. If the RETURN key was 
pressed, control is transferred out of 
the loop and line 20 is executed. 

10 DOPEN #8,"SEQFILE"This program opens file "SEQFILE" 



20 DO 

30 GET #8,A$ 

40 PRINT A$; 

50 LOOP UNTIL ST 

60 DOLOSE #8 



and gets data until the ST system 
variable indicates all data is input. 
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— Open a disk file for a read and/or write operation 

DOPEN #logical file number,"filename[,<SfP>]"[,Lrecorcl 
length][,Ddrive number][<ON | ,>Udevice 
number][,w] 

wliere: 

S = Sequential File Type 

P = Program File Type 

L = Record Length = the length of records in a relative file only 

W = Write Operation (if not specified a read operation occurs) 

This statennent opens a sequential, relative or randonn access file 
for a read or write operation. The record length (L) pertains to a rela- 
tive file, which can be as long as 255. The "W" parameter is speci- 
fied only during a write (PRINT#) operation in a sequential file. If it is 
not specified, the disk drive assumes the disk operation to be a read 
operation. 

The logical file number associates a number to the file for future disk 
operatons such as a read (input#) or write (print#) operation. The 
logical file number can range from 1 to 255. Logical file numbers 
greater than 1 28 automatically send a carriage return and linefeed 
with each write (print#) command. Logical file numbers less than 
1 28 send only a carriage RETURN, which can be suppressed with a 
semicolon at the end of the print# command. The default device 
number is 8, and the default drive is 0. 

EXAMPLES: 

D0PEN#1, "ADDRESS",W Open the sequential file number 1 

(ADDRESS) for a write operation 

D0PEN#2 "RECIPES",D1,U9 Open the sequential file number 2 

(RECIPES) for a read operation on 
device number 9, drive 1 



— Draw dots, lines and shapes at specified positions on screen 

DRAW [color source], [XI , Y1 ][TO X2, Y2] . . . 

This statement draws individual dots, lines, and shapes. Here are the 
parameter values: 

where: 



Color source 



Bit map background 

1 Bit map foreground 

2 Multicolor 1 

3 Multicolor 2 
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X1,Y1 Starting coordinate (0,0 througii 

320.200) 
X2,Y2 Ending coordinate (0,0 through 

320,200) 

The X and Y values can place the pixel cursor at absolute coordi- 
nates such as (100,100) or at coordinates relative to the previous 
position ( 4- / - X and + / - y) of the pixel cursor such as ( + 20, - 1 0). 
The coordinate of one axis (x or y) can be relative and the other can 
be absolute. Here are the possible combinations of ways to specify 
the X and y coordinates: 

x,y absolute x, absolute y 

+ / - x,y relative x, absolute y 

X, + / - y absolute x, relative y 

+ / - X, + / - y relative x, relative y 

Also see the LOCATE command for information on the pixel cursor. 

The graphics commands DRAW, BOX. CIRCLE, PAINT LOCATE AND 
GSHAPE have an additional notation which allows you to specify a 
distance and an angle relative to the previous coordinates of the 
pixel cursor (PC). The notation is as follows: 

KEYWORD source, distance; angle 

where: 

KEYWORD is a graphics command such as DRAW, 

CIRCLE, PAINT LOCATE. BOX or GSHAPE 

SOURCE is the same code as in all of the graphics 

commands 

DISTANCE is the number of pixels to move the pixel 
cursor 

ANGLE is the number of degrees to move relative to 

the previous pixel cursor coordinate 

EXAMPLES: 

DRAW 1, 100, 50 Draw a dot. 

DRAW , 10,10 TO 100,60 Draw a line. 

DRAW , 10,10 TO 10,60 TO 100,60 TO 10,10 Draw a triangle 

DRAW Draw a dot at the present pixel cursor position. Use 
LOCATE to position the pixel cursor. 
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You may omit a parameter but you still must include the comma that 
would have followed the unspecified parameter. Omitted parameters 
take on the default values. 



^ DSAVE 
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—Save a BASIC program file to disk 

DSAVE "filename" [,Ddrive number][<ON | ,>Udevlce 
number] 

This command stores (SAVEs) a BASIC program on disk. (See SAVE 
to store programs on tape.) A filename up to 1 6 characters long must 
be supplied. The default device number is 8, while the default drive 
number is 0. 



EXAMPLES: 

DSAVE "BANKRECS" 

DSAVE (A$) 

DSAVE "PROG 3",D1,U9 



SAVES the program "BANKRECS" to 
disk. 

SAVES the disk program named in 
the variable A$. 

SAVES the program "PROG 3" to 
disk on unit number 9, drive 1. 



n DVERIFY 



—Verify the program in memory against the one on disk 



DVERIFY "filename"[,Ddrive number][<ON | ,>Udevice 
number] 

This command causes the Commodore 128 to check the program 
on the specified drive against the program in memory The default 
drive number is and the default device number is 8. 

NOTE: If a graphic area is allocated or reallocated after a SAVE, an 
error occurs. Because BASIC text is moved from its original (SAVEd) 
location when a bit mapped graphics area is allocated or dealloca- 
ted, the original location where the CI 28 verified the SAVEd program 
changes. Hence, VERIFY, which performs byte-to-byte comparisons, 
fails, even though the program is valid. Make sure to VERIFY or 
DVERIFY immediately after issuing the SAVE command to avoid this 
problem. 



n 
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To verify Binary data, see VERIFY "filename", 8,1 format, under 
VERIFY command description. 



EXAMPLES: 
DVERIFY "C128" 



Verifies program "C128" on drive 0, 
unit 8. 



DVERIFY "SPRITES",D0,U9 Verifies program "SPRITES" on 

drive 0, device 9. 



u 

IJ 
u 



END 



— Define the end of program execution 

END 

When the program encounters the END statement, it stops RUNning 
immediately. The CONT command can be used to restart the pro- 
gram at the next statement (if any) following the END statement. 



ENVELOPE 



— Define a musical instrument envelope 

ENVELOPE n[,atk] [,dec] Lsus] Lrel][,wf] [,pw ] 

where: 

n Envelope number (0-9) 

atk Attack rate (0-15) 

dec Decay rate (0-15) 

sus Sustain (0-15) 

rel Release rate (0-15) 

wf Waveform: = triangle 

1 = sawtooth 

2 = variable pulse (square) 

3 = noise 

4 = ring modulation 
pw Pulse width (0-4095) 

A parameter that is not specified will retain its predefined or cur- 
rently redefined value. Pulse width applies to the width of the varia- 
ble pulse waveform (wf = 2) only and is determined by the formula 
pwout = pw/40.95. The Commodore 128 has initialized the following 
10 envelopes: 
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n 


A 


D 


S 


R 


wf 


pw 


instrument 


ENVELOPE 


0, 


0, 


9, 


0, 


0, 


2, 


1536 


piano 


ENVELOPE 


1, 


12, 


0, 


12, 


0, 


1 




accordion 


ENVELOPE 


2, 


0, 


0, 


15, 


0, 







calliope 


ENVELOPE 


3, 


0, 


5, 


5, 


0, 


3 




drum 


ENVELOPE 


4, 


9, 


4, 


4, 


0, 







flute 


ENVELOPE 


5, 


0, 


9, 


2, 


1, 


1 




guitar 


ENVELOPE 


6, 


0, 


9. 


0, 


0, 


2, 


512 


harpsichord 


ENVELOPE 


7, 


0, 


9, 


9, 


0, 


2, 


2048 


organ 


ENVELOPE 


8, 


8, 


9, 


4, 


1, 


2, 


512 


trunnpet 


ENVELOPE 


9, 


0, 


9, 


0, 


0, 







xylophone 



To play predefined musical instrument envelopes.you can simply 
specify the envelope number and omit the rest of the parameters 
since they retain their predefined values. 



FAST 



— Put machine in 2 MHz mode of operation 

FAST 

This command initiates 2MHz mode, causing the VIC 40-column 
screen to be turned off. All operations (except I/O) are speeded up 
considerably Graphics may be used, but will not be visible until a 
SLOW command is issued. The Commodore 1 28 powers up in 1 MHz 
mode. 



FETCH 



— Get data from expansion (RAM module) memory 
FETCH #bytes, intsa, expsa, expb 

where bytes = number of bytes to get from expansion memory 
(1-65536) 
intsa = starting address of host ram (0-65535) 
expb = 64k expansion RAM bank number (0-3) 
expsa= starting address of expansion RAM (0-65535) 

The host BANK is selected with the BANK command. 
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— Define sound (SID chip) filter parameters 
FILTER [f req] Lip] [.bp] [,hp] [,re8] 

where: 

freq Filter cut-off frequency (0-2047) 

Ip Low-pass filter on (1), off (0) 

bp Bank-pass filter on (1 ), off (0) 

hp High-pass filter on (1), off (0) 

res Resonance (0-15) 

Unspecified parameters result in no change to the current value. 

You can use more than one type of filter at a time. For example, both 
low-pass and high-pass filters can be used together to produce a 
notch-(or band-reject) filter response. For the filter to have an audible 
effect, at least one type of filter must be selected and at least one 
voice must be routed through the filter. 

EXAMPLES: 

FILTER 1024,0,1,0,2 Set the cutoff frequency at 1024, 

select the band pass filter and a 
resonance level of 2. 

FILTER 2000,1,0,1,10 Set the cutoff frequency at 2000, 

select both the low pass and high 
pass filters (to form a notch reject) 
and set the resonance level at 10. 



u 
u 
u 



u 



u 
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FORfTOfSTEPf 
NEXT 



— Define a repetitive program loop structure. 

FOR variable = start value TO end value [STEP Increment] 

This statement works with the NEXT statement to set up a section of 
the program (i.e., a loop) that repeats for a set number of times. This 
is useful when something needs to be counted or something must be 
done a certain number of times (such as printing). 

This statement executes all the commands enclosed between the 
FOR and NEXT statements repetitively according to the start and 
end values. The start value and the end value are the beginning and 
ending counts for the loop variable. The loop variable is added to or 
subtracted from during the FOR/NEXT loop. 
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The logic of the FOR/NEXT statement is as follows. First, the loop 
variable is set to the start value. When the progrann reaches a pro- 
gram line containing the NEXT statement, it adds the STEP incre- 
ment (default = 1 ) to the value of the loop variable and checks to 
see if it is higher than the end value of the loop. If the loop variable is 
less than the end value, the loop is executed again, starting with the 
statement immediately following the FOR statement. If the loop vari- 
able is greater than the end value, the loop terminates and the pro- 
gram resumes immediately following the NEXT statement. The oppo- 
site is true if the step size is negative. See also the NEXT statement. 

EXAMPLE: 

10 FOR L = 1 TO 10 

20 PRINT L 

30 NEXT L 

40 PRINT "I'M DONE! L = "L 

This program prints the numbers from one to 10 followed by the mes- 
sage I'M DONE! L= 11. 

The end value of the loop may be followed by the word STEP and 
another number or variable. In this case, the value following the 
STEP is added each time instead of one. This allows counting back- 
wards, by fractions, or in increments other than one. 

The user can set up loops inside one another. These are known as 
nested loops. Care must be taken when nesting loops so the last 
loop to start is the first one to end. 

EXAMPLE: 

10 FOR L = 1 TO 100 

20 FOR A = 5 TO 11 STEP .5 

30 NEXT A 

40 NEXT L 

The FOR . . . NEXT loop in lines 20 and 30 are nested inside the one 
in line 10 and 40. Using a STEP increment of .5 is used to illustrate 
the fact that floating point indices are valid. 



GET 



— Receive input data from the keyboard, one character at a time, 
without waiting for a key to be pressed 

GET variable list 

The GET statement is a way to receive data from the keyboard, one 
character at a time. When GET is encountered in a program, the 
character that is typed is stored in the 0128 memory If no character 
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is typed, a null (empty) character is returned, and the program con- 
tinues without waiting for a key There is no need to hit the RETURN 
key The word GET is followed by a variable name, either numeric or 
string. 

If the C1 28 intends to GET a numeric key and a key besides a num- 
ber is pressed, the program stops and an error message is dis- 
played. The GET statement may also be put into a loop, checking for 
an empty result. The GETKEY statement could also be used in this 
case. See GETKEY for more information. The GET and GETKEY 
statements can be executed only within a program. 



EXAMPLE: 

10 DO:GETA$:LOOP UNTIL A$ = "A" 



20 GET B, C, D 



This line waits for the A key 
to be pressed to continue. 

GET numeric variables B,C 
and D from the keyboard 
without waiting for a key to 
be pressed. 



U 

U 
\ ( 



GETKEY 



— Receive input data from tlie keyboard, one cliaracter at a time and 
wait for a l<ey to be pressed 

GETKEY variable list 

Tiie GETKEY statement is very similar to the GET statement. Unlil<e 
the GET statement, GETKEY waits for the user to type a character 
on the l<eyboard. This lets the computer wait for a single character to 
be typed. This statement can be executed only within a program. 

EXAMPLE: 

10 GETKEY A$ 

This line waits for a key to be pressed. Typing any key continues the 
program. 

10 GETKEY A$,B$,C$ 

This line waits for three alphanumeric characters to be entered from 
the keyboard. 
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G064 



— Receive input data from a tape, disk or RS232 

GET# file number, variable list 

Tliis statement inputs one cliaracter at a time from a previously 
opened file. Otherwise, it works like the GET statement. This state- 
ment can be executed only within a program. 



EXAMPLE: 
10GET#1,A$ 



This example receives one character, which is 
stored in the variable A$, from file number 1. 
This example assumes that file 1 was 
previously opened. See the OPEN statement. 



— Switch to C64 mode 

G064 

This statement switches from CI 28 mode to C64 mode. The ques- 
tion "Are You Sure?" is displayed in response to the G064 statement. 
If Y is typed, then the currently loaded program is lost and control is 
given to C64 mode; otherwise, if any other key is pressed, the com- 
puter remains in CI 28 mode. This statement can be used in direct 
mode or within a program. The prompt is not displayed in program 
mode. 



GOSUB 



n 



n 



I [ 



— Call a subroutine from the specified line number 

GOSUB line number 

This statement is similar to the GOTO statement, except the Commo- 
dore 1 28 returns from where it came when the subroutine is finished. 
When a line with a RETURN statement is encountered, the program 
jumps back to the statement immediately following the GOSUB 
statement. 

The target of a GOSUB statement is called a subroutine. A subrou- 
tine is useful if a task is repeated several times within a program. 
Instead of duplicating the section of program over and over, set up a 
subroutine, and GOSUB to it at the appropriate time in the program. 
See also the RETURN statement. 
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GOTO/GOTO 



GRAPHIC 



EXAMPLE: 
20 GOSUB 800 



This example calls the subroutine beginning at 
line 800 and executes it. All subroutines must 
terminate with a RETURN statement. 



800 PRINT "HI THERE": RETURN 

—Transfer program execution to the specified line number 

GOTO line number 

After a GOTO statement is encountered in a program, the computer 
executes the statement specified by the line number in the GOTO 
statement. When used in direct mode, GOTO executes (RUNs) the 
program starting at the specified line number without clearing the 
variables. This is the same as the RUN command except it does not 
clear variable values. 

EXAMPLES: 

10 PRINT"COMMODORE" The GOTO in line 20 makes line 10 

20 GOTO 10 repeat continuously until RUN/STOP is 

pressed. 



GOTO 100 



Starts (RUNs) the program starting at 
line 100, without clearing the variable 
storage area. 



— Select a graphic mode 

1) GRAPHIC mode [,clear][,s] 

2) GRAPHIC CLR 

This statement puts the Commodore 128 in one of the six graphic 
modes: 

mode description 

40-column text 

1 standard bit-map graphics 

2 standard bit-map graphics (split screen) 

3 multicolor bit-map graphics 

4 multicolor bit-map graphics (split screen) 

5 80-column text 



u 
u 
u 



u 
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The clear parameter specifies whether the bit mapped screen is 
cleared (equal to 1) upon running the program, or left intact (equal to 
0). The S parameter indicates the starting line number of the split 
screen when in graphic mode 2 or 4 (multicolor or standard bit map 
split screen modes). The default starting line number of the split 
screen is 19. 

When executed, GRAPHIC 1-4 allocates a 9K-bit mapped area. The 
start of BASIC text area is moved above the bit-map area, and any 
BASIC program is automatically relocated. This area remains allo- 
cated even if the user returns to TEXT mode (GRAPHIC 0). If the 
clear option is specified as 1 , the screen is cleared. The GRAPHIC 
CLR command deallocates the 9k, bit-mapped area, places it in its 
original location below the bit-mapped area and makes it available 
once again for BASIC text . 



EXAMPLES: 
GRAPHIC 1,1 

GRAPHIC 4,0,10 

GRAPHIC 
GRAPHIC 5 
GRAPHIC CLR 



Select standard bit map mode and clear the 
bit map. 

Select split screen multicolor bit map mode, 
do not clear the bit map and start the split 
screen at line 10. 

Select 40-column text. 

Select 80-column text. 

Clear and deallocate the bit map screen. 



HEADER 



— Format a diskette 

HEADER "diskname" [,l i.d.] [i Ddrive number] 

[<ON I ,>Udevice number] 

Before a new disk can be used for the first time, it must be formatted 
with the HEADER command. The HEADER command can also be 
used to erase a previously formatted disk, which can then be reused. 

When you enter a HEADER command in direct mode, the prompt 
ARE YOU SURE? appears. In program mode, the prompt does not 
appear. 

This command divides the disk into sections called blocks. It creates 
a table of contents of files, called a directory The diskname can be 
any name up to 1 6 characters long. The i.d. number is any two alpha- 
numeric characters. Give each disk a unique i.d. number. Be careful 
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when using the HEADER comnnand because it erases all stored 
data. 

You can HEADER a diskette quicker if it was already formatted, by 
onnitting the new disk i.d. number. The old i.d. number is used. The 
quick header can be used only if the disk was previously formatted, 
since it clears out the directory rather than formatting the disk. The 
default device number is 8. The drive number must be specified (0 
for a single disk drive). 

As a precaution, the system asks "ARE YOU SURE?" before the 
Commodore 1 28 completes the operation. Press the "Y" key to per- 
form the HEADER, or press any other key to cancel it. 

The HEADER command reads the disk command error channel, and 
if an error is encountered, the error message "?BAD DISK ERROR" 
is displayed. 

The HEADER command is analogous to the BASIC 2.0 command: 
OPEN 1,8,15,"N0:diskname,i.d." 
EXAMPLES: 
HEADER "MYDISK", 123, DO 



HEADER "RECS", 145, D1 ON U9 



This HEADERS "MYDISK" 
using i.d. 23 on drive 0, 
(default) device number 8. 

This HEADERS "RECS" using 
i.d. 45, on Drive 1, device 
nunnber 9 



HEADER "C128 PROGRAMS", DO This is a quick header on 

drive 0, device nunnber 8, 



HEADER (A$),I(B$),D0,U9 



assuming the disk in the drive 
was already formatted. The 
old i.d. is used. 

This example HEADERS the 
diskette with the name 
specified by the variable A$, 
and the i.d. specified by the 
variable B$, on drive 0, 
device number 9. 
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IF/THEN/ELSE 



— Highlight the line where the error occurred 

HELP 

The HELP command is used after an error has been reported in a 
program. When HELP is typed in 40-column format, the line where 
the error occurs is listed, with the portion containing the error dis- 
played in reverse field. In 80-column format, the portion of the line 
where the error occurs is underlined. 



— Evaluate a conditional expression and execute portions of a pro- 
gram depending on the outcome of the expression 

IF expression THEN statements [:ELSE else-clause] 

The IF. .. THEN statement evaluates a BASIC expression and takes 
one of two possible courses of action depending upon the outcome 
of the expression. If the expression is true, the statement(s) following 
THEN is executed. This can be any BASIC statement. If the expres- 
sion is false, the program resumes with the program line immedi- 
ately following the program line containing the IF statement, unless 
an ELSE clause is present. The entire IF. . . THEN statement must be 
contained within 1 60 characters. Also see BEGI N/BEN D. 

The ELSE clause, if present, must be on the same line as the IF. . . 
THEN portion of the statement, and separated from the THEN 
clause by a colon. When an ELSE clause is present, it is executed 
only when the expression is false. The expression being evaluated 
may be a variable or formula, in which case it is considered true if 
nonzero, and false if zero. In most cases, there is an expression 
involving relational operators (=,<,),< = ,> = ,<». 

The IF. . . THEN statement can take two additional forms: 

IF expression THEN line number 

or: 
IF expression GOTO line number 

These forms transfer program execution to the specified line number 
if the expression is true. Otherwise, the program resumes with the 
program line number immediately following the line containing the IF 
statement. 

EXAMPLE: 

50 IF X > THEN PRINT "OK": ELSE END 

This line checks the value of X. If X is greater than 0, the statement 
immediately following the keyword THEN (PRINT "OK") is executed 
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99 STOP 

100 PRINT "X equals 10" 



and the ELSE clause is ignored. If X is less than or equal to 0, the 
ELSE clause is executed and the statennent imnnediately following 
THEN is ignored. 

10 IF X = 10 THEN 100 This example evaluates the 

value of X. IF X equals 10, the 

20 PRINT "X does not equal 10" program control is transferred to 

line 100 and the message "X 
EQUALS 10" Is printed. IPX 
does not equal 10, the program 
resumes with line 20, the C128 
prints the prompt "X does not 
equal 10" and the program 
stops. 



— Receive a data string or a nunnber f ronn the keyboard and wait for 
the user to press RETURN 

INPUT ["prompt string";] variable list 

The INPUT statennent asks for data f ronn the user while the program 
is RUNning and places the data into a variable or variables. The pro- 
gram stops, prints a question mark (?) on the screen, and waits for 
the user to type the answer and hit the RETURN key. The word 
INPUT is followed by a prompt string and a variable name or list of 
variable names separated by commas. The message in the prompt 
string inside quotes suggests (prompts) the information the user 
should enter. If this message is present, there must be a semicolon 
(;) after the closing quote of the prompt. 

When more than one variable is INPUT, separate them by commas. 
The computer asks for the remaining values by printing two question 
marks (??). If the RETURN key is pressed without INPUTting a value, 
the INPUT variable retains the value previously input. The INPUT 
statement can be executed only within a program. 

EXAMPLE: 

10 INPUT "PLEASE TYPE A NUMBER";A 

20 INPUT "AND YOUR NAME";A$ 

30 PRINT A$ "YOU TYPED THE NUMBER";A 



U 
U 

u 
u 
u 
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— Inputs data from a file into the connputer's mennory 

INPUT# file number, variable list 

This statement works like INPUT, but takes the data from a previously 
OPENed file, usually on a disk or tape instead of the keyboard. No 
prompt string is used. This statement can be used only within a pro- 
gram. 

EXAMPLE: 

10 OPEN 2,8,2 

20 INPUT#2, A$, C, D$ 

This statement INPUTS the data stored in variables A$, C and D$ 
from the disk file number 2, which was OPENed in line 1 0. 

— Define or list function key assignments 

KEY [key number, string] 

There are eight function keys (F1-F8) available to the user on the 
Commodore 128: four unshifted and four shifted. The Commodore 
128 allows you to perform a function or operation for each time the 
specified function key is pressed. The definition assigned to a key 
can consist of data, or a command or series of commands. KEY with 
no parameters specified returns a listing displaying all current KEY 
assignments. If data is assigned to a function key that data is dis- 
played on the screen when that function key is pressed. The maxi- 
mum length for all the definitions together is 241 characters. 

EXAMPLE: 

KEY 7, "GRAPHICO" + CHR$(13) + "LIST" + CHR$(13) 

This tells the computer to select the (VIC) text screen and list the 
program whenever the F7 key is pressed (in direct mode). CHR$(1 3) 
is the ASCII character for RETURN and performs the same action as 
pressing the RETURN key Use CHR$(27) for ESCape. Use CHR$(34) 
to incorporate the double quote character into a KEY string. The 
keys may be redefined in a program. For example: 

10 KEY2,"PRINT DS$" + CHR$(13) 

This tells the computer to check and display the disk drive error 
channel variables (PRINT DS$) each time the F2 function key is 
pressed. 

10 FOR I = 1 to 8:KEY I, CHR$(I + 132):NEXT 

This defines the function keys as CHR$ 133 through CHR$ 140. 
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To restore all function keys to their BASIC default values, reset the 
Comnnodore 128 by pressing the RESET button. 



—Assigns a value to a variable 

[LET] variable = expression 

The word LET is rarely used in programs, since it is not necessary 
Whenever a variable is defined or given a value, LET is always 
implied. The variable name that receives the result of a calculation is 
on the left side of the equal sign. The number, string or formula is on 
the right side. You can only assign one value with each (implied) LET 
statement. For example, LET A = B = 2 is illegal. 

EXAMPLE: 

10 LET A = 5 Assign the value 5 to numeric variable A. 

20 B = 6 Assign the value 6 to numeric variable B. 

30C = A*B + 3 Assign the numeric variable C, the value 
resulting from 5 times 6 plus 3. 

40 D$ = "HELLO" Assign the string "HELLO" to string variable 
D$. 



u 
u 
u 



LIST 



— List the BASIC program currently in memory 

LIST [first line] [ - iast line] 

The LIST command displays a BASIC program listing that has been 
typed or LOADed into the Commodore 128's memory so you can 
read and edit it. When LIST is used alone (without numbers following 
it), the Commodore 128 gives a complete LISTing of the program on 
the screen. The listing process may be slowed down by holding 
down the COMMODORE key, paused by CONTROL S or NO SCROLL 
KEY (and resumed by pressing any other key), or stopped by hitting 
the RUN/STOP key If the word LIST is followed by a line number, the 
Commodore 128 shows only that line number. If LIST is typed with 
two numbers separated by a dash, all lines from the first to the sec- 
ond line number are displayed. If LIST is typed followed by a number 
and just a dash, the Commodore 128 shows all lines from that num- 
ber to the end of the program. And if LIST is typed with a dash, then a 
number, all lines from the beginning of the program to that line num- 
ber are LISTed. By using these variations, any portion of a program 
can be examined or brought to the screen for modification. In Com- 
modore 1 28 mode, LIST can be used in a program and the program 
can resume with the CONT command. 
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EXAMPLES: 




LIST 


Shows entire program. 


LIST 100- 


Shows from line 100 until the end of the 
program. 


LIST 10 


Shows only line 10. 


LIST -100 


Shows all line from the beginning through line 
100. 


LIST 10-200 


Shows lines from 10 to 200, inclusive. 



n 
n 

n 
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— Load a program from a peripheral device sucii as tlie disk drive or 
Datassette 

LOAD ^'f ilename" [^device number] [,relocate flag] 

Tliis is the command used to recall a program stored on disk or cas- 
sette tape. Here, the filename is a program name up to 16 charac- 
ters long, in quotes. The name must be followed by a comma (out- 
side the quotes) and a number which acts as a device number to 
determine where the program is stored (disk or tape). If no number is 
supplied, the Commodore 128 assumes device number 1 (the Datas- 
sette tape recorder). 

The relocate flag is a number (0 or 1) that determines where a pro- 
gram is loaded in memory. A relocate flag of tells the Commodore 
1 28 to load the program at the start of the BASIC program area. A 
flag of 1 tells the computer to LOAD from the point where it was 
SAVEd. The default value of the relocate flag is 0. The program 
parameter of 1 is generally used when loading machine language 
programs. 

The device most commonly used with the LOAD command is the 
disk drive. This is device number 8, though the DLOAD command is 
more convient to use when working with disk. 

If LOAD is typed with no arguments, followed by RETURN, the 01 28 
assumes you are loading from tape and you are prompted to "PRESS 
PLAY ON TAPE". If you press PLAY, the Commodore 128 starts look- 
ing for a program on tape. When the program is found, the Commo- 
dore 128 prints FOUND"filename", where the filename is the name 
of the first file which the Datassette finds on the tape. Press the 
Commodore key to LOAD the found filename, or press the spacebar 
to keep searching on the tape. Once the program is LOADed, it can 
be RUN, LISTed or modified. 
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EXAMPLES: 

LOAD 

LOAD "HELLO" 

LOAD (A$),8 

L0AD"HELL0",8 

L0AD"MACHLANG"A1 



Reads in the next program fronn tape. 

Searches tape for a program called 
HELLO, and LOADs it if found. 

LOADS the program from disk whose 
name is stored in the variable A$. 

Looks for the program called HELLO on 
disk drive number 8, drive 0. (This is 
equivalent to DLOAD "HELLO"). 

LOADS the machine language program 
called "MACHLANG" into the location 
from which it was SAVEd. 



The LOAD connmand can be used within a BASIC program to find 
and RUN the next program on a tape or disk. This is called chaining. 



LOCATE 



— Position the bit map pixel cursor on the screen 

LOCATE x,y 

The LOCATE statement places the pixel cursor (PC) at any specified 
pixel coordinate on the screen. 

The pixel cursor (PC) is the coordinate on the bit map screen where 
drawing of circles, boxes, lines and points and where PAINTing 
begins. The PC ranges from X and Y coordinates 0,0 through 
320,200. The PC is not visible like the text cursor but it can be con- 
trolled through the graphics statements (BOX,CIRCLE,DRAW etc.) 
The default location of the pixel cursor is the coordinate specified as 
the X and Y portions in each particular graphics command. So the 
LOCATE command does not have to be specified. 

The X and Y values can place the pixel cursor at absolute coordi- 
nates such as (100,100) or at coordinates relative to previous posi- 
tion ( + / - X and + / - y) of the pixel cursor such as ( + 20, - 1 0). The 
coordinate of one axis (x or y) can be relative and the other can be 
absolute. Here are the possible combinations of ways to specify the 
x and y coordinates: 



x,y 

+ /-x,y 
x, + /-y 
+ /-x, + /-y 



absolute x, absolute y 
relative x, absolute y 
absolute x, relative y 
relative x, relative y 
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The graphics commands DRAW, BOX, CIRCLE, PAINT, LOCATE AND 
GSHAPE have an additional notation which allows you to specify a 
distance and an angle relative to the previous coordinates of the 
pixel cursor (PC). The notation is as follows: 



KEYWORD 

where: 

KEYWORD 

SOURCE 

DISTANCE 

ANGLE 

EXAMPLE: 
LOCATE 160,100 

LOCATE +20,100 



source, distance; angle 



is a graphics command such as DRAW, 
CIRCLE, PAINT LOCATE, BOX or GSHAPE 

is the same code as in all of the graphics 
commands 

is the number of pixels to move the pixel 
cursor 

is the number of degrees to move relative to 
the previous pixel cursor coordinate 



Positions the PC in the center of the bit map 
screen. Nothing will be seen until something 
is drawn. 

Move the pixel cursor 20 pixels to the right of 
the last PC position and place it at Y 
coordinate 100. 

LOCATE - 30, + 20 Move the PC 30 pixels to the left and 20 
down from the previous PC position. 

The PC can be found by using the RDOT(O) function to get the X- 
coordinate and RD0T(1) to get the Y-coordinate. The color source of 
the dot at the PC can be found by PRINTing RD0T(2). 



MONITOR 



— Enter the Commodore 128 machine language monitor 

MONITOR 

See Appendix J for details on the Commodore 128 Machine Lan- 
guage Monitor. 
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— Position or move sprite on the screen 

1) MOVSPR number,x,y Place the specified sprite at absolute 

coordinate x,y. 

2) MOVSPR number, +l-x, +/-y 

Move sprite relative to the position of the 
pixel cursor. 

3) MOVSPR iiumber|X;y Move sprite distance x at angle y relative 

to the pixel cursor. 

4) MOVSPR number,x angle #y speed 

Move sprite at an angle (x) relative to its 
original coordinates, in the clockwise 
direction and at the specified speed (y). 

where: 

number is sprite's number (1 through 8) 
<,x,y> is coordinate of the sprite location. 

ANGLE is the angle (0-360) of motion in the clockwise direction rela- 
tive to the sprites original coordinate. 

SPEED is a speed (0-15) in which the sprite moves. 

This statennent locates a sprite at a specific location on the screen 
according to the SPRITE coordinate plane (not the bit map plane) or 
initiates sprite motion at a specified rate. See MOVSPR in Section 6 
for a diagram of the sprite coordinate system. 

EXAMPLES: 



MOVSPR 1,150,150 
MOVSPR 1, + 20, -30 
MOVSPR 4, -50, +100 

MOVSPR 5, 45 #15 



Position sprite 1 near the center of 
the screen, x,y coordinate 150,150. 

Move sprite 1 to the right 20 
coordinates and up 30 coordinates. 

Move sprite 4 to the left 50 
coordinates and down 100 
coordinates. 

Move sprite 5 at a 45 degree angle 
in the clockwise direction, relative to 
its original x and y coordinates. The 
sprite moves at the fastest rate (15). 

NOTE: Once you specify an angle and a speed in the third form of 
the MOVSPR statement, you must set the angle back to zero before 
moving other sprites, or their movement will be affected. Also, keep 
in mind that the SCALE command affects the MOVSPR coordinates. 
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NEW 



If you add SCALing to your programs, you also must adjust the 
sprites new coordinates so they appear correctly on the screen. 

— Clear (erase) program and variable storage 

NEW 

This command erases the entire program in memory and clears any 
variables that may have been used. Unless the program was stored 
on disk or tape, it is lost. Be careful with the use of this command. 
The NEW command also can be used as a statement in a BASIC 
program. However, when the Commodore 1 28 gets to this line, the 
program is erased and everything stops. 
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— Conditionally branch to a specified program line number accord- 
ing to the results of the specified expression 

ON expression <GOTO/GOSUB> line #1 [, line #2, . . . ] 

This statement can make the GOTO and GOSUB statements operate 
like special versions of the (conditional) IF statement. The word ON is 
followed by a logical or mathematical expression, then either of the 
keywords GOTO or GOSUB and a list of line numbers separated by 
commas. If the result of the expression is 1 , the first line in the list is 
executed. If the result is 2, the second line number is executed and 
so on. If the result is 0, or larger than the number of line numbers in 
the list, the program resumes with the line immediately following the 
ON statement. If the number is negative, an ILLEGAL QUANTITY 
ERROR results. 

EXAMPLE: 

10 INPUT X:IF X<0 THEN 10 

20 ON X GOTO 30, 40, 50, 60 When X= 1,0N sends control to the 



25 STOP 



30 PRINT "X 
40 PRINT "X 
50 PRINT "X 
60 PRINT "X 



1" 
2" 
3" 
4" 



first line number in the list (30) 
When X = 2, ON sends control to the 
second line (40),etc 



OPEN 



— Open files for input or output 

OPEN logical file number, device number [^secondary 
address] [^''filename, filetype, mode"]/[|Cmd string]) 
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The OPEN statement allows the Commodore 128 to access files 
within devices such as a disk drive, a Datassette cassette recorder, 
a printer or even the screen of the Commodore 1 28. The word OPEN 
is followed by a logical file number, which is the number to which all 
other BASIC input/output statements will refer, such as 
PRINT#(write), INPUT#(read), etc. This number is from to 255. 

The second number, called the device number, follows the logical file 
number. Device number is the Commodore 128 keyboard; 1 is the 
cassette recorder; 3 is the Commodore 128 screen, 4-7 are the 
printer(s); and 8-1 1 are reserved for disk drives. It is often a good 
idea to use the same file number as the device number because it 
makes it easy to remember which is which. 

Following the device number may be a third parameter called the 
secondary address. In the case of the cassette, this can be for 
read, 1 for write and 2 for write with END-OF-TAPE marker at the 
end. In the case of the disk, the number refers to the channel num- 
ber. See your disk drive manual for more information on channels 
and channel numbers. For the printer, the secondary addresses are 
used to select certain programming functions. 

There may also be a filename specified for disk or tape OR a string 
following the secondary address, which could be a command to the 
disk/tape drive or the name of the file on tape or disk. If the filename 
is specified, the type and mode refer to disk files only File types are 
PROGRAM, SEQUENTIAL, RELATIVE and USER; modes are READ 
and WRITE. 



EXAMPLES: 
10 OPEN 3,3 
20 OPEN 1,0 



OPENS the screen as file number 3. 
OPENS the keyboard as file number 1 . 



30 OPEN 1,1,0,"DOT" OPENs the cassette for reading, as file 
number 1, using "DOT" as the filename. 



OPEN 4,4 
OPEN 15,8,15 



OPENs the printer as file number 4. 

OPENs the command channel on the disk 
as file 15, with secondary address 15. 
Secondary address 15 is reserved for the 
disk drive error channel. 



u 
u 
u 
u 
u 
u 
u 
u 
u 

LI 



276 



BASIC 7.0 ENCYCLOPEDIA— Basic Commands and Statements 



n 
n 
n 



5 OPEN 8,8,12,"TESTFILE,SEQ,WRITE" OPENs a sequential disk 

file for writing called 
TESTFILE as file 
number 8, with 
secondary address 12. 

See also: CLOSE, CMD, GET#, INPUT#, and PRINT# statennents and 
systenn variables ST, DS, and DS$. 



PAINT 



1 i 



— Fill area with color 

PAINT [color source],x,y[,mode] 

where: 

color source Bit map foreground 

1 Bit map background (default) 

2 Multicolor 1 

3 Multicolor 2 

x,y starting coordinate, scaled (default at 

pixel cursor (PC)) 

mode = paint an area defined by the color 

source selected 

1 = paint an area defined by any non- 
background source 

The PAINT comnnand fills an area with color. It fills in the area around 
the specified point until a boundary of the sanne source is encoun- 
tered. For example, if you draw a circle in the foreground color 
source, start PAINTing the circle where the coordinate assunnes the 
background source. The Commodore 1 28 will only PAINT where the 
specified source in the PAINT statement is different than the source 
of the X and y pixel coordinate. It cannot PAINT points where the 
sources are the same in the PAINT statement and the pixel coordi- 
nate. The X and y coordinate must lie completely within the boundary 
of the shape you intend to PAINT and the source of the starting pixel 
coordinate and the specified color source must be different. 

The X and y values can place the pixel cursor at absolute coordi- 
nates such as (100,100) or at coordinates relative to previous posi- 
tion ( + / - X and + / - y) of the pixel cursor such as ( + 20, - 1 0). The 
coordinate of one axis is (x or y) can be relative and the other can be 
absolute. Here are the posible combinations of ways to specify the 
X and y coordinates: 

x,y absolute x, absolute y 
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+ / - x,y relative x, absolute y 

X, + / - y absolute x, relative y 

+ / - X, + / - y relative x, relative y 

Also see the LOCATE command for information on the pixel cursor. 

The graphics commands DRAW, BOX, CIRCLE, RAINT LOCATE AND 
GSHAPE have an additional notation which allows you to specify a distance 
and an angle relative to the previous coordinates of the pixel cursor (PC). 
The notation is as follows: 



KEYWORD 

where: 

KEYWORD 

SOURCE 

DISTANCE 

ANGLE 



source, distance; angle 



is a graphics command such as DRAW, 
CIRCLE, PAINT LOCATE, BOX or GSHAPE 

is the same code as in all of the graphics 
commands 

is the number of pixels to move the pixel 
cursor 

is the number of degrees to move relative to 
the previous pixel cursor coordinate 



EXAMPLE: 

10 CIRCLE 1, 160,100,65,50 

20 PAINT 1, 160,100 



10 BOX 1, 10, 10, 20, 20 
20 PAINT 1, 15, 15 

30 PAINT 1, +10, +10 



Draws an outline of a circle. 

Fills in the circle with color from 
source 1 (VIC foreground), assuming 
point 160,100 is colored in the 
background color (source 0). 

Draws an outline of a box. 

Fills the box with color from source 
1, assuming point 15,15 is colored in 
the background source (0). 

PAINT the screen in the foreground 
color source at the coordinate 
relative to the pixel cursor's previous 
position plus 10 in both the vertical 
and horizontal positions. 



PLM 



—Defines and plays nnusical notes and elements within a string or 
string variable. 
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PLAY"Vn,On,Tii,Un,Xn,elementS|notes" 

where the string or string variable is composed of the following: 

Vn = Voice (n = 1-3) 

On = Octave (n = 0-6) 

Tn = Tune Envelope Defaults (n = 0-9) 

= piano 

1 = accordion 

2 = calliope 

3 = drunn 

4 = flute 

5 = guitar 

6 = harpsichord 

7 = organ 

8 = trumpet 

9 = xylophone 
Un = Volume (n = 0-8) 

Xn = Filter on (n = 1), off (n = 0) 

Notes: A,B,C,D,E,F,G 

Elements: # Sharp 

$ Flat 

W Whole note 

H Half note 

Q Quarter note 

I Eighth note 

S Sixteenth note 

Dotted 

R Rest 

M Wait for all voices cur- 
rently playing to end 
the current "measure" 

The PLAY statement gives you the power to select voice, octave and 
tune envelope (including ten predefined musical instrument enve- 
lopes), the volume and the notes you want to PLAY All these controls 
are enclosed in quotes. You may include spaces in a PLAY string for 
readability 

All elements except R and M precede the musical notes in a PLAY 
string. 
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POKE 



EXAMPLES: 

PLAY "V1O4T0U5X0CDEFGAB" Play the notes C.D,E,F,G.A 

and B in voice 1, octave 4, 
tune envelope (piano), at 
volunne 5, with the filter 
off. 

PLAY "V305T6U7X1#B$AW.CHDQEIF"Play the notes B sharp, A 

flat, a whole dotted-C note, 
a half D-note, a quarter E- 
note and an eighth F-note. 



A$ = "V305T6U3ABCDE" 
PLAY A$ 



PLAY the notes and 
elements within A$. 



— Change the contents of a RAM nnennory location 

POKE address, value 

The POKE statennent allows changing of any value in the Connnno- 
dore 128 RAM, and allows nnodification of nnany of the Connnnodore 
128 Input/Output registers. The keyword POKE is always followed by 
two paranneters. The first is a location inside the Comnnodore 128 
nnemory. This can be a value f ronn to 65535. The second paranneter 
is a value fronn to 255, which is placed in the location, replacing 
any value that was there previously. The value of the nnennory loca- 
tion deternnines the bit pattern of the nnennory location. The POKE 
occurs into the currently selected RAM bank. The POKE address 
depends on the BANK nunnber. See BANK in this Encyclopedia for 
the appropriate BANK configurations. 

EXAMPLE: 

10 POKE 53280,1 Changes VIC border color 

NOTE: PEEK, a function related to POKE, returns the contents of the 
specified nnennory location, is listed under FUNCTIONS. 



PRINT 



— Output to the text screen 

PRINT [print list] 

The PRINT statennent is the nnajor output statennent in BASIC. While 
the PRINT statennent is the first BASIC statement nnost people learn 
to use, there are nnany variations of this statennent. The word PRINT 
can be followed by any of the following: 



Characters inside quotes 



("text") 
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Variable names 
Functions 
Punctuation marl^s 



(A, B, A$, X$) 
(SIN(23),ABS(33)) 



The characters inside quotes are often called literals because they 
are printed literally, exactly as they appear. Variable names have the 
value they contain (either a number or a string) printed. Functions 
also have their number values printed. 

Punctuation marks are used to help format the data neatly on the 
screen. The comma separates printed output by 10 spaces, while 
the semicolon separates printed output by three spaces. Either 
punctuation mark can be used as the last symbol in the statement. 
This results in the next PRINT statement acting as if it is continuing 
the previous PRINT statement. 

EXAIVIPLES: RESULTS 

10 PRINT "HELLO" HELLO 

20 A$ = "THERE":PRINT "HELLO ";A$ HELLO THERE 

30A = 4:B = 2:?A+B 6 

40 J = 41:PRINT J;:PRINT J - 1 41 40 

50 PRINT A;B;:D = A + B:PRINT D;A-B 4 2 6 2 

See also PCS, SPG, TAB and CHAR functions. 



PRINT # 



— Output data to files 

PRINT# file number, print list 

PRINT# is followed by a number which refers to the data file previ- 
ously OPENed. The number is followed by a comma and a list of 
items to be output to the file which can be strings, numeric or string 
variables or numeric data. The comma and semicolon act in the 
same manner for spacing with printers as they do in the PRINT state- 
ment. Some devices may not work with TAB and SPC. 



EXAMPLE: 

10 OPEN 4,4 

20 PRINT#4,"HELL0 THERE!",A$,B$ 



10 OPEN 2,8,2 

20 PRINT#2,A,B$,C,D 



Outputs the data "HELLO 
THERE" and the variables 
A$ and B$ to the printer. 

Outputs the data variables 
A, B$, C and D to the disk 
file number 2. 
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PRINT USING 



NOTE: The PRINT* command is used by itself to close the channel 
to the printer before closing the file, as follows: 

10 OPEN 4,4 

30 PRINT#4,"PRINT WORDS" 

40 PRiNT#4 

50 CLOSE 4 



— Output using format 

PRINT [#filenumber,] USING"format list"; print list 

This statement defines the format of string and numeric items for 
printing to the text screen, printer or other device. The format is put 
in quotes. This is the format list. Then add a semicolon and a list of 
what is to be printed in the format for the print list. The list can be 
variables or the actual values to be printed. 

EXAMPLE: 

5 X = 32: Y = 100-23: A$ = "CAT" 
10 PRINT USING "$##.## ";13.25,X,Y 
20 PRINT USING "###>#";"CBM",A$ 

When this is RUN, line 10 prints: 

$13.25 $32.00 $***** Five asterisks (*****) are printed 

instead of a Y value because Y has five 
digits, and this condition does not con- 
form to format list (as explained below) 



Line 20 prints this: 
CBM CAT 

CHARACTER 

Pound sign (#) 
Plus sign ( + ) 
Minus sign (-) 
Decimal Point (.) 
ConnmaO 
Dollar Sign ($) 
Four Up Arrows (tttt) 
Equal Sign ( = ) 
Greater Than Sign (» 



Leaves three spaces before printing 
"CBM" as defined in format list. 

NUMERIC STRING 



X 
X 
X 
X 
X 
X 
X 



X 



X 
X 
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The pound sign (#) reserves roonn for a single cliaracter in the output 
field. If the data itenn contains more characters than there are # 
signs in the format field, the entire field is filled with asterisks (*); no 
characters are printed. 

EXAMPLE: 

10 PRINT USING "####";X 

For these values of X, this format displays: 

A = 12.34 12 

A = 567.89 568 

A = 123456 **** 

For a STRING item, the string data is truncated at the bounds of the 
field. Only as many characters are printed as there are pound signs 
(#) in the format item. Truncation occurs on the right. 

The plus ( + ) and minus ( - ) signs can be used in either the first or 
last position of a format field, but not both. The plus sign is printed if 
the number is positive. The minus sign is printed if the number is 
negative. 

If a minus sign is used and the number is positive, a blank is printed 
in the character position indicated by the minus sign. 

If neither a plus nor a minus sign is used in the format field for a 
numeric data item, a minus sign is printed before the first digit or 
dollar symbol if the number is^negative. No sign is printed if the num- 
ber is positive. This means that one additional character, the minus 
sign, is printed if the number is negative. If there are too many char- 
acters to fit into the field specified by the pound sign and plus/minus 
signs, then an overflow occurs and the field is filled with asterisks 
(*). 

A decimal point (.) symbol designates the position of the decimal 
point in the number. There can be only one decimal point in any for- 
mat field. If a decimal point is not specified in the format field, the 
value is rounded to the nearest integer and printed without decimal 
places. 

When a decimal point is specified, the number of digits preceding 
the decimal point (including the minus sign, if the value is negative) 
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must not exceed the number of pound signs before the decimal 
point. If there are too many digits, an overflow occurs and the field is 
filled with asterisks (*). 

A comma (.) allows placing of commas in numeric fields. The posi- 
tion of the comma in the format list indicates where the commas 
appear in a printed number. Only commas within a number are 
printed. Unused commas to the left of the first digit appear as filler 
character. At least one pound sign must precede the first comma in 
afield. 

If commas are specified in a field and the number is negative, then a 
minus sign is printed as the first character, even if the character posi- 
tion is specified as a comma. 



EXAMPLES: 
FIELD EXPRESSION 


RESULT 


COMMENT 


##.# 


-.1 


-0.1 


Leading zero added. 


##.# 


1 


1.0 


Trailing zero added. 


#### 


-100.5 


-101 


Rounded to no decimal 
places. 


#### 


-1000 


* * • * 


Overflow because four 
digits and a minus sign 
cannot fit in field. 


###. 


10 


10. 


Decimal point added. 


#$## 


1 


$1 


Floating dollar sign. 



A dollar sign ($) symbol shows that a dollar sign will be printed in the 
number. If the dollar sign is to float (always be placed before the 
number), at least one pound sign must be specified before the dollar 
sign. If a dollar sign is specified without a leading pound sign, the 
dollar sign is printed in the position shown in the format field. If com- 
mas and/or a plus or minus sign are specified in a format field with a 
dollar sign, the program prints a comma or sign before the dollar 
sign. The up arrows or caret symbols (aa) are used to specify that 
the number is to be printed in E + format (scientific notation). A 
pound sign must be used in addition to the four carets to specify the 
field width. The carets can appear either before or after the pound 
sign in the format field. Four carets must be specified when a num- 
ber is to be printed in E format. If more than one but fewer than four 
carets are specified, a syntax error results. If more than four carets 
are specified, only the first four are used. The fifth caret is inter- 
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READ 



n 
n 



preted as a no-text symbol. An equal sign ( = ) is used to center a 
string in a field. The field width is specified by the nunnber of charac- 
ters (pound sign and equal sign) in the format field. If the string con- 
tains fewer characters than the field width, the string is centered in 
the field. If the string contains more characters that can be fit into 
the field, then the right-most characters are truncated and the string 
fills the entire field. A greater than sign (» is used to right justify a 
string in a field. 



—Redefine symbols in PRINT USING statement 

PUDEF "nnnn" 

Where "nnnn" is any combination of characters, up to four in all, 
PUDEF allows you to redefine any of the following four symbols in 
the PRINT USING statement: blanks, commas, decimal points and 
dollar signs. These four symbols can be changed into some other 
character by placing the new character in the correct position in the 
PUDEF control string. 

Position 1 is the filler character. The default is a blank. Place a new 
character here for another character to appear in place of blanks. 

Position 2 is the comma character. Default is a comma. 

Position 3 is the decimal point. Default is a decimal point. 

Position 4 is the dollar sign. Default is a dollar sign. 
EXAMPLES: 

10 PUDEF "*" PRINTS * in the place of blanks. 

20 PUDEF " <" PRINTS < in the place of commas. 

— Read data from DATA statements and input it into the computer's 
memory (while the program is RUNning) 

READ variable list 

This statement inputs information from DATA statements and stores 
it in variables, where the data can be used by the RUNning program. 
The READ statement variable list may contain both strings and num- 
bers. Be careful to avoid reading strings where the READ statement 
expects a number and vice versa. This produces a TYPE MISMATCH 
ERROR message. 
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The data in the DATA statements are READ in sequential order. Each 
READ statement can read one or more data items. Every variable in 
the READ statement requires a data item. If one is not supplied, an 
OUT OF DATA ERROR occurs. 

In a program, you can READ the data and then re-read it by issuing 
the RESTORE statement. The RESTORE sets the sequential data 
pointer back to the beginning, where the data can be read again. See 
the RESTORE statement. 



EXAMPLES: 

10 READ A, B, C 
20 DATA 3, 4, 5 



READ the first three numeric 
variables from the closest data 
statement. 



10 READ A$, B$, C$ READ the first three string 

20 DATA JOHN, PAUL, GEORGE string variables from the nearest 

data statement. 



10 READ A, B$, C 

20 DATA 1200, NANCY, 345 



READ (and input into the C128 
memory) a numeric variable, a 
string variable and another 
numeric variable. 



RECORD 



— Position relative file pointers 

RECORD# logical file number, record number [,byte 
number] 

This statement positions a relative file pointer to select any byte 
(character) of any record in the relative file. The logical file number 
can be in the range between and 255. The record number can be 
in the range through 65535. Byte number is in the range 1 through 
254. See your disk drive manual for details about relative files. 

When the record number value is set higher than the last record 
number in the file, the following occurs: 

For a write (PRINT#) operation, additional records are created to 
expand the file to the desired record number. 

For a read (INPUT#) operation, a null record is returned and a 
"RECORD NOT PRESENT ERROR occurs". 
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EXAMPLES: 

10 OPEN 2,8,2"CUSTOMER,R,W" 
20 RECORD#2,10,1 
30 PRINT#2,A$ 
40 CLOSE 2 

This example opens an existing relative file called "CUSTOMER" as 
file number 2 in line 1 0. Line 20 positions the relative file pointer at 
the first byte in record number 1 0. Line 30 actually writes the data, 
A$, to file number 2. 

The RECORD command accepts variables for its parameters. It is 
often convienent to place a RECORD command within a FOR . . . 
NEXT or DO loop. Also see DOPEN and OPEN. 



REM 



— Comments or remarks about the operation of a program line 

REM message 

The REMark statement is a note to whoever is reading a listing of the 
program. REM may explain a section of the program, give informa- 
tion about the author, etc. REM statements do not affect the opera- 
tion of the program, except to add length to it (and therefore use 
more memory). Nothing to the right of the keyword REM is inter- 
preted by the computer as an executable instruction. Therefore, no 
other executable statement can follow a REM on the same line. 

EXAMPLE: 

10 NEXT X:REM This line increments X. 



RENAME 



— Change the name of a file on disk 

RENAME "old filename" TO "new filename" [,Dclrive 
number] [,Udevice number] 

This command is used to rename a file on a disk, from the old 
filename to the new filename. The disk drive does not RENAME a file 
if it is OPEN. 



EXAMPLES: 

RENAIWE "TEST" TO "FINALTEST",DO Change the name of the 

file "TEST" to "FINAL 
TEST". 
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RENAME (A$) to (B$),D0,U9 



Change the filename 
specified in A$ to the 
filename specified in B$ 
on drive 0, device 
number 9. Remember, 
whenever a variable 
name is used as a 
filename, it must be 
enclosed in parentheses. 



— Renunnber lines of a BASIC progrann 

RENUMBER [new starting line number][,increment] [,oicl 
starting line number] 

The new starting line is the nunnber of the first line in the progrann 
after renumbering; the default value is 1 0. The incrennent is the inter- 
val between line numbers, (i.e., 10, 20, 30, etc.); the increment 
default value is also 10. The old starting line number is the first line 
number before you renumber the program. This allows renumbering 
of a select portion of the program. The default in this case is the first 
line of the program. This command can only be executed from direct 
mode. 

An "UNRESOLVED REFERENCE" error occurs if any reference to 
line number that doesn't exist is encountered. A "LINE NUMBER 
TOO LARGE" error occurs if RENUMBERing expands the program 
beyond its limits. Either error leaves the program unharmed. 



EXAMPLES: 
RENUMBER 



RENUMBER 20, 20, 1 



RENUMBER, , 65 



Renumbers the program starting at 
10, and increments each additional 
line by 10. 

Starting at line 1, renumbers the 
program. Line 1 becomes line 20, 
and other lines are numbered in 
increments of 20. 

Starting at line 65, renumbers in 
increments of 10. Line 65 becomes 
line 10. If you omit a parameter, you 
must still enter a comma as a 
placeholder. 



u 
u 
u 
u 
u 



u 



u 
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RESTORE 



RESUME 



—Reset READ pointer so the DATA can be reREAD 

RESTORE [line #] 

When executed in a progrann, the pointer to the itenn in a DATA state- 
ment that is to be read next is reset to the first itenn in the DATA state- 
nnent. This provides the capability to reREAD the data. If a line num- 
ber follows the RESTORE statement, the READ pointer is set to the 
first data item in the specified program line. Otherwise the pointer is 
reset to the beginning of the BASIC program. 



EXAMPLES: 

10 FOR I = 1 TO 3 

20 READ X 

30 TOTAL = X + TOTAL 

40 NEXT 

50 RESTORE 

60 GOTO 10 

70 DATA 10,20,30 



10 READ A,B,C 
20 DATA 100,500,750 
30 READ X,Y,Z 
40 DATA 36,24,38 
50 RESTORE 40 
60 READ S,P,Q 



This example READs the data 

in line 70 and stores it in 

numeric variable X. It adds 

the total of all the numeric 

data items. Once all the data 

has been READ, three cycles through 

the loop, the READ pointer is 

RESTOREd to the beginning of the 

program and it returns to line 10 and 

performs repetitively. 

This example RESTORES the DATA 

pointer to the beginning data 

item in line 40. When line 60 

is executed, it will READ the 

DATA 36,24,38 from line 40, 

since you don't need to READ line 20's 

DATA again. 



— Define where the progrann will continue (RESUME) after an error 
has been trapped 

RESUME [line # I NEXT] 

This statennent is used to restart progrann execution after TRAPping 
an error. With no paranneters, RESUME attennpts to re-execute the 
statennent in which the error occurred. RESUME NEXT resunnes 
execution at the statennent innmediately following the one containing 
the error; RESUME followed by a line number will GOTO the specific 
line and resume execution from that line number. RESUME can only 
be used in program mode. 

EXAMPLE: 

10 INPUT "dENTER A NUMBER";A 
15 TRAP 100 
20B = 100/A 
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40 PRINT'THE RESULT =";B: PRINT"THE END" 

50 INPUT "DO YOU WANT TO RUN IT AGAIN (Y/N)";Z$:IF 

Z$ = "Y"THEN10 

60 STOP 

100 INPUT"ENTER ANOTHER NUMBER (NOT ZERO)";A 

110 RESUME 20 

This example traps a "division by zero error" in line 20 if is entered 
in line 10. If zero is entered, the program goes to line 100, where you 
are asked to input another number besides 0. Line 110 returns to line 
20 to complete the calculation. Line 50 asks if you want to repeat the 
program again. If you do, press the Y key 



RETURN 



—Return from subroutine 

RETURN 

This statement is always paired with the GOSUB statement. When 
the program encounters a RETURN statement, it goes to the state- 
ment immediately following the last GOSUB command executed. If 
no GOSUB was previously issued, then a RETURN WITHOUT 
GOSUB ERROR message is displayed and the program stops. All 
subroutines end with a RETURN statement. 

EXAMPLE: 

10 PRINT "ENTER SUBROUTINE" 

20 GOSUB 100 

30 PRINT "END OF SUBROUTINE" 



90 STOP 

100 PRINT "SUBROUTINE 1" 

110 RETURN 

This example calls the subroutine at line 1 00 which prints the mes- 
sage "SUBROUTINE 1 " and RETURNS to line 30, the rest of the 
program. 



RUN 



— Execute BASIC program 

1) RUN [line #] 

2) RUN "filename" [jDdrive nuniber][,Udevice number] 

Once a program has been typed into memory or LOADed, the RUN 
command executes it. RUN clears all variables in the program 
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SAVE 



before starting program execution. If there is a nunnber following the 
RUN connnnand, execution starts at that line nunnber. If there is a 
filenanne following the RUN comnnand, the nanned file is loaded from 
the disk drive and RUN, with no further action required of the user. 
RUN may be used within a program. The default drive number is 
and default device number is 8. 



EXAMPLES: 
RUN 

RUN 100 
RUN"PRG1" 

RUN(A$) 



Starts execution from the beginning of the 
program. 

Starts program execution at line 100. 

DLOADS "PRG1" from disk drive 8, and runs 
it from the starting line number. 

DLOADs the program named in the variable 
A$. 



— Store the program in memory to disk or tape 

SAVE ["f ilename"][,device number][,EOT flag] 

This command stores a program currently in memory onto a cas- 
sette tape or disk. If the word SAVE is typed alone followed by 
RETURN, the Commodore 1 28 assumes that the program is to be 
stored on cassette tape. It has no way of checking if there is already 
a program on the tape in that location, so make sure you do not 
record over valuable information on your tape. If SAVE is followed by 
a filename in quotes or a string variable name, the Commodore 128 
gives the program that name, so it may be located easily and 
retrieved in the future. If a device number is specified for the SAVE, 
follow the name with a comma (after the quotes) and a number or 
numeric variable. Device number 1 is the tape drive, and number 8 is 
the disk drive. After the device number on a tape command, there 
can be a comma and a second number, which is 2. If the 2 is 
present, the Commodore 128 puts an END-OF-TAPE marker (EOT 
flag) after the program (tape output only). If, in trying to LOAD a pro- 
gram, the Commodore 1 28 finds one of these markers, rather than 
loading the program, a FILE NOT FOUND ERROR is reported. 



EXAMPLES: 

SAVE 

SAVE "HELLO' 

SAVE A$,8 



Stores program on tape, without a name. 

Stores a program on tape, under the name 

HELLO. 

Stores on disk, with the name stored in 

variable A$. 
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SAVE "HELLO", 8 Stores on disk, with name HELLO (equivalent 

to DSAVE "HELLO"). 
SAVE "HELLO", 1, 2 Stores on tape, with nanne HELLO, and 

places an END-OF TAPE marker after the 

program. 



— Alter scaling in graphics nnode 
SCALE n [|Xmax,ymax] 

where: 

n = 1 (on) or (off) 

In Standard bit map mode 320 < =X max < 32767 

(default = 1023) 
200< = Ymax < 32767 
(default = 1023) 

In Multicolor mode 160 < =X max < 32767 

(default = 511) 
160<=Ymax< 32767 
(default = 511) 

This statennent changes the scaling of the bit nnaps in nnulticolor and 
high-resolution modes. Entering: 

SCALE 1 

turns scaling on. Coordinates nnay then be scaled f ronn to 32767 in 
both X and Y, rather than the nornnal scale values, which are: 

multicolor mode X = to 159 Y = to 199 

bit map mode X = to 319 Y = to 199 

EXAMPLES: 

10 GRAPHIC 1,1 Enter standard bit 

20 SCALE IrCIRCLE 1,180,100,100,100 map, turn scaling on to 

default size (1023,1023) 
and draw a circle. 
10 GRAPHIC 3,1 Enter multicolor mode, 

20 SCALE 1,1000,5000 turn scaling on to size 

30 CIRCLE 1,180,100,100,100 (1000,5000) and draw a 

circle. 

The SCALE connnnand affects the sprite coordinates in the MOVSPR 
connnnand. If you add scaling to a progrann that contains sprites, 
adjust the MOVSPR coordinates accordingly. 
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SCRATCH 



SLEEP 



— Clear screen 
SCNCLR mode number 

The modes are as follows: 



Mode Number 


1 
2 
3 
4 
5 



Mode 

40 column (VIC) text 

bit map 

split screen bit map 

multicolor bit map 

split screen multicolor bit map 

80 column (8563) text 



This statement with no argument clears the graphic screen, if it is 
present, otherwise the current text screen is cleared. 

EXAMPLES: 

SCNCLR 5 Clears 80 column text screen. 

SCNCLR 1 Clears the (VIC) bit map screen. 

SCNCLR 4 Clears the (VIC) split screen multicolor bit map. 



— Delete a file from the disk directory 

SCRATCH "filename" [,Ddrive number][,Udevice number] 

This command deletes a file from the disk directory. As a precaution, 
the system asks "ARE YOU SURE?" (in direct mode only) before the 
Commodore 128 completes the operation. Type a Y to perform the 
SCRATCH or press any other key to cancel the operation. Use this 
command to erase unwanted files, and to create more space on the 
disk. The filename may contain template, or wildcards (?,* etc.). The 
default drive number is and default device number is 8. 

EXAMPLE: 

SCRATCH "MY BACK", DO 

This erases the file MY BACK from the disk in drive 0. 



— Delay program for a specific period of time 
SLEEP N 

where N is seconds 0< N < 65535. 
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SLOW 



SOUND 



—Return the Commodore 1 28 to 1 Mhz operation 

SLOW 

The Commodore 1 28 is capable of running the 8502 microprocessor 
at a speed of 1 or 2 megahertz (Mhz). 

The SLOW command slows down the microprocessor to 1 Mega- 
hertz from 2 Megahertz. The FAST command sets the Commodore 
at 2 Mhz. The Commodore 1 28 can process internally substantially 
faster at 2 Mhz than at 1 Mhz. However, there is no increase in the 
speed of input and output to peripherals. The 8502 microprocessor 
defaults to 1 Mhz speed. 

— Output sound effects and musical notes 
SOUND v,f,d[,clir]I,m][,sl[,wl[,pl 



voice (1..3) 

frequency value (0..65535) 

duration (0..32767) 

step direction (0(up) ,1(down) or 2(oscillate)) default = 

minimum frequency (if sweep is used) (0..65535) 

default = 

step value for sweep (0..32767) default = 

waveform (0 = triangle, 1 =sawtooth,2 = variable, 

3 = noise) default = 2 

pulse width (0..4095) default = 2048 



where : v = 
f = 
d = 
dir = 
m = 

s = 
w = 

P = 

The SOUND command is a fast and easy way to create sound 
effects and musical tones. The three required parameters v,f and d 
select the voice, frequency and duration of the sound. The duration 
is in units called jiffies. Sixty jiffies equals 1 second. 

The SOUND command can sweep through a series of frequencies 
which allows sound effects to pass through a range of notes. Specify 
the direction of the sweep with the DIR parameter. Set the minimum 
frequency of the sweep with M and the step value of the sweep with 
S. Select the appropriate waveform with W and specify P as the 
width of the variable pulse waveform if selected in W. 



u 
u 



\ i 



I I 
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u 
u 
u 
u 
u 



EXAMPLES: 
SOUND 1,40960,60 



Play a SOUND at frequency 40960 
in voice 1 for 1 second. 
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SPRCOLOR 



SPRDEF 



SOUND 2,20000,50,0,2000,100 Output a sound by sweeping 

through frequencies starting at 
2000 and incrennenting upward in 
units of 100 up to 20,000. Each 
frequency is played for 50 jiffies. 

SOUND 3,5000,90,2,3000,500,1 This example outputs a range of 

sounds starting at a mininnum 
frequency of 3000, through 5000, in 
increments of 500. The direction of 
the sweep is back and forth 
(oscillating). The selected waveform 
is sawtooth and the voice selected 
is 3. 



— Set multicolor 1 and/or multicolor 2 colors for all sprites 
SPRCOLOR [smcr-1][,smcr-2] 

where: 

smcr-1 Sets multicolor 1 for all sprites. 
smcr-2 Sets multicolor 2 for all sprites. 

Either of these parameters may be any color from 1 through 16. 

EXAMPLES: 

SPRCOLOR 3,7 Sets sprite multicolor 1 to red and multicolor 2 to 

blue. 
SPRCOLOR 1,2 Sets sprite multicolor 1 to black and multicolor 2 to 

white. 

— Enter the SPRite DEFinition mode to create and edit sprite 
images. 

SPRDEF 

The SPRDEF command defines sprites interactively. 

Entering the SPRDEF command, displays a sprite work area on the 
screen which is 24 characters wide by 21 characters tall. Each char- 
acter position in the grid corresponds to a sprite pixel in the sprite 
displayed to the right of the work area. Here is a summary of the 
SPRite DEFinition mode operations and the keys that perform them: 
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User Input 


Description 


1-8 


Selects a sprite number. 


A 


Turns on and off automatic cursor 




movement. 


CRSR keys 


Moves cursor. 


RETURN key 


Moves cursor to start of next line. 


RETURN key 


Exits sprite designer mode at the SPRITE 




NUMBER? prompt only. 


HOME key 


Moves cursor to top left corner of sprite 




work area. 


CLR key 


Erases entire grid. 


1-4 


Selects color source. 


CTRL key, 1-8 


Selects sprite foreground color (1-8). 


Commodore key, 1-8 


Selects sprite foreground color (9-16). 


STOP key 


Cancels changes and returns to prompt. 


SHIFT RETURN 


Saves sprite and returns to SPRITE 




NUMBER? prompt. 


X 


Expands sprite in X (horizontal) direction. 


Y 


Expands sprite in Y (vertical) direction. 


M 


Multicolor sprite. 


C 


Copies sprite data from one sprite to 




another. 



SPRITE 



—Turn on and off, color, expand and set screen priorities for a sprite 

SPRITE (number) [,onlofn[9fgnd][,priority][,x-exp] 
[,y-exp][,mo<ie] 

The SPRITE statement controls most of the characteristics of a 
sprite. 



Parameter 

number 

on/off 

foreground 

priority 



x-exp 
yexp 
mode 



Description 

Sprite number (1-8) 

Turn sprite on (1) or off (0) 

Sprite foreground color (1-16) 

Priority is if sprites appear in front of objects on 

the screen. Priority is 1 If sprites appear in back of 

objects on the screen. 

Horizontal EXPansion on (1) or off (0) 

Vertical EXPansion on (1) or off (0) 

Select standard sprite (0) or multicolor sprite (1) 



U 
U 



i J 






u 



u 



1 / 
I I 

u 
u 
u 
u 
u 
u 



Unspecified parameters in subsequent sprite statennents take on the 
characters of the previous SPRITE statement. You may check the 
characteristics of a SPRITE with the RSPRITE function. 
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SSHAPEIGSHAPE 



EXAMPLES: 



SPRITE 1,1,3 
SPRITE 2,1,7,1,1,1 



Turn on sprite number 1 and color it red. 
Turn on sprite number 2, color it blue 
make it pass behind objects on the 
screen and expand it in the vertical and 
horizontal directions. 
SPRITE 6,1,1,0,0,1,1 Turn on SPRITE number 6, color it black. 
The first tells the computer to display 
the sprites in front of objects on the 
screen. The second and the 1 
following tell the C128 to expand the 
sprite verticaly only The last 1 specifies 
multicolor mode. Use the SPRCOLOR 
command to select the sprite's 
multicolor. 

— Store sprite data f ronn a text string variable into a sprite storage 
area or vice versa 

SPRSAV < origin), (destination) 

This connnnand transfers a sprite innage f ronn a string variable to a 
sprite storage area. It can also transfer the data from the sprite stor- 
age area into a string variable. Either the origin or the destination 
can be a sprite nunnber or a string variable but they both cannot be 
string variables. If you are nnoving a string into a sprite, only the first 
63 bytes of data are used. The rest are ignored since a sprite can 
only hold 63 data bytes. 

EXAMPLES: 

SPRSAV 1,A$ Transfers the image pattern from sprite 1 to the 

string named A$. 
SPRSAV B$,2 Transfers the data from string variable B$ into 

sprite 2. 
SPRSAV 2,3 Transfers the data from sprite 2 to sprite 3. 



— Save/retrieve shapes to/f ronn string variables 

SSHAPE and GSHAPE are used to save and load rectangular areas 
of multicolor or bit mapped screens to/f ronn BASIC string variables. 
The command to save an area of the screen into a string variable is: 

SSHAPE string variable, XI , Y1 [,X2,Y2] 
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where: 



place shape as is (default) 
invert shape 
OR shape with area 
AND shape with area 
XOR shape with area 



The replacement nnode allows you to change the data in the string 
variable so you can invert it, perfornn a logical OR, exiusive OR or 
AND operation on the image. The X and Y values can place the pixel 
cursor at absolute coordinates such as (100,100) or at coordinates 
relative to the previous position ( + / - X and + / - Y) of the pixel cur- 
sor such as ( + 20, - 1 0). The coordinate of one axis (X or Y) can be 
relative and the other can be absolute. Here are the posible combi- 
nations of ways to specify the X and Y coordinates. 

x,y absolute x, absolute y 

+ /-x,y relative x, absolute y 

X, + / - y absolute x, relative y 

+ / - X, + / - y relative x, relative y 
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L! 



String variable String name to save data in 

X1,Y1 Corner coordinate (0,0 through 319,199) 

(scaled) j } 

X2,Y2 Corner coordinate opposite (XI ,Y1) — ' 

(default is the PC) 

Because BASIC limits strings to 255 characters, the size of the area LJ 
that can be saved is limited. The string size required can be calcu- 
lated using one of the following (unsealed) formulas: 

L(mcm)=INT((ABS(X1-X2) + 1)/4 + .99) * (ABS(Y1 - Y2)+ 1) + 4 

L(h- r)= INT ( (ABS(X1 -X2) + 1) / 8 + .99) * (ABS(Y1 - Y2)+ 1) + 4 

The first equation pertains to multicolor bit map mode; the second 
equation applies to standard bit map mode. 

The command to retrieve (load) the data from a string variable and 
display it on specified screen coordinates is: 

GSHAPE string variable LX,Y] [,mode] 

where: 

string Contains shape to be drawn 

X,Y Top left coordinate (0,0 through 319,199) telling 

where to draw the shape (scaled— the default is 

the pixel cursor) 
mode Replacement mode: 



u 



u 



/ I 



( \ 



Also see the LOCATE command for information on the pixel cursor. 



(0») 
(360°) 



270" 



PC 



180« 



(90°) 



n 



/ \ 



The graphics commands DRAW, BOX, CIRCLE, PAINT, LOCATE AND 
GSHAPE have an additional notation which allows you to specify a 
distance and an angle relative to the previous coordinates of the 
pixel cursor (PC). The notation is as follows: 

KEYWORD source, distance; angle 
where: 

KEYWORD 

SOURCE 

DISTANCE 

ANGLE 

EXAMPLES: 
SSHAPE A$,10,10 

SSHAPE B$,20,30,47,51 
SSHAPE D$, + 10, + 10 



is a graphics command such as DRAW, 
CIRCLE, PAINT LOCATE. BOX or GSHAPE 

is the same code as in all of the graphics 
commands 

Is the number of pixels to move the pixel 
cursor 

is the number of degrees to move relative to 
the previous pixel cursor coordinate 



Saves a rectangular area from the 
coordinates 10,10 to the location of the 
pixel cursor, into string variable A$. 
Saves a rectangular area from top left 
coordinate (20,30) through bottom right 
coordinate (47,51) into string variable 
B$. 

Saves a rectangular area 10 pixels to 
the right and 10 pixels down from the 
current position of the pixel cursor. 
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GSHAPE A$,120,20 



GSHAPE B$,30,30,1 



GSHAPE C$, +20, + 30 



Retrieves shape contained in string 
variable A$ and displays it at top left 
coordinate (120,20). 
Retrieves shape contained in string 
variable B$ and displays it at top left 
coordinate 30,30. The shape is inverted 
due to the replacement mode being 
selected by the 1 . 

Retrieve shape from string variable C$ 
and displays it 20 pixels to the right and 
30 pixels down from the current position 
of the pixel cursor. 



NOTE: Beware using modes 1-4 with multicolor shapes. You may 
obtain unpredictable results. 



u 
u 

u 
u 

u 



STASH 



— Move contents of host memory to expansion RAM 
STASH #bytes, intsa, expsa, expb 

Refer to FETCH command for description of parameters. 



STOP 



— Halt program execution 

STOP 

This statement halts the program. A message, BREAK IN LINE XXX, 
occurs (only in program mode), where XXX is the line number con- 
taining the STOP command. The program can be restarted at the 
statement following STOP if the CONT command is used immedi- 
ately, without any editing occurring in the listing. The STOP state- 
ment is often used while debugging a program. 



SWAP 



— Swap contents of host RAM with contents of expansion RAM 
SWAP #bytes, Intsa, expsa, expb 

Refer to FETCH command for description of parameters. 



SYS 



— Call and execute a machine language subroutine at the specified 
address 

SYS address [,al [,xl [,yl [,sl 

This statement performs a call to a subroutine at a given address in a 
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TEMPO 



TRAP 



memory configuration set up according to tine BANK command. 
Optionally, arguments a,x,y and s are loaded into the accumulator, x, 
y and status registers, respectively before the subroutine is called. 

The address range is to 65535. The program begins executing the 
machine-language program starting at that memory location. Also 
see the BANK command. 



EXAMPLES: 
SYS 40960 

SYS 8192,0 



Calls and executes the machine-language routine at 
location 40960. 

Calls and executes the machine-language routine at 
location 8192 and load zero into the accumulator. 



— Define the speed of the song being played 
TEMPO n 

where n is a relative duration between (1 and 255) 

The actual duration for a whole note is determined by using the for- 
mula given below: 

whole note duration = 19.22/n seconds 

The default value is 8, and note duration increases with n. 

EXAMPLES: 

TEMPO 16 Defines the Tempo at 16. 

TEMPO 1 Defines the TEMPO at the slowest speed. 

TEMPO 250 Defines the TEMPO at 250. 

— Detect and correct program errors while a BASIC program is 
RUNning 

TRAP [line #] 

When turned on, TRAP intercepts most error conditions (excluding 
DOS error messages but including the STOP KEY) except an 
"UNDEF'D STATEMENT ERROR." In the event of any execution 
error, the error flag is set and execution is transferred to the line 
number specified in the TRAP statement. The line number in which 
the error occurred can be found by using the system variable EL. 
The specific error condition is contained in system variable ER. The 
string function ERR$ (ER) gives the error message corresponding to 
any error condition. 

The RESUME statement can be used to resume program execution. 
TRAP with no line number turns off error trapping. An error in a TRAP 
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TROFF 



TROU 



VERIFY 



routine cannot be trapped. Also see system variables ST, DS and 
DS$. 

EXAMPLES: 

100 TRAP 1000 If an error occurs, go to line 1000. 

1000 ?ERR$ (ER);EL Print the error message, and the error 

number. 
1010 RESUME Resume with program execution. 

—Turn off error tracing nnode 
TROFF 

This statennent turns off trace mode. 

—Turn on error tracing mode 

TRON 

TRON is used in program debugging. This statement begins trace 
mode. When you RUN the program, the line numbers of the program 
appear in brackets before any action for that line occurs. 

— Verify program in memory against one saved to disk or tape 

VERIFY "filename" [,devlce number] [.relocate flag] 

This command causes the Commodore 1 28 to check the program 
on tape or disk against the one in memory to determine if the pro- 
gram is really SAVEd. This command is also very useful for position- 
ing a tape so that the Commodore 1 28 writes after the last program 
on the tape. It will do so, and inform the user that the programs don't 
match. The tape is then positioned properly and the next program 
can be stored without fear of erasing the old one. 

VERIFY, with no arguments after the command, causes the Commo- 
dore 128 to check the next program on tape, regardless of its name, 
against the program now in memory VERIFY, followed by a program 
name in quotes or a string variable in parentheses, searches the 
tape for that program and then checks it against the program in 
memory when found. VERIFY, followed by a name, a comma and a 
number, checks the program on the device with that number (1 for 
tape, 8 for disk). The relocate flag is the same as in the LOAD com- 
mand. It verifies the program from the memory location from which 
it was SAVEd. 



EXAMPLES: 
VERIFY 



Checks the next program on the tape. 



302 



BASIC 7.0 ENCYCLOPEDIA— Basic Commands and Statements 



u 
u 
u 
u 

u 
u 
u 
u 
u 
u 
u 
u 
u 
u 
u 
u 
u 



/ I 



/ \ 



VOL 



J i 



WAIT 



n 



I \ 



n 



VERIFY "HELLO" Searches for HELLO on tape, checks it 

against mennory. 
VERIFY "HELLO", 8,1 Searches for HELLO on disk, then checks 

it against mennory. 

NOTE: If a graphic area is reallocated for use after a SAVE, VERIFY 
and DVERIFY will report an error. Technically this is correct. BASIC 
text in this case has been moved from its original (saved) location 
to another address range. Hence, VERIFY which performs byte-to- 
byte comparisons, will fail, even though the program is valid. 

— Define output level of sound 

VOL volume level 

This statement sets the volunne for SOUND and PLAY statements. 
VOLUME level can be set from to 1 5, where 1 5 is the maximum 
volume, and is off. VOL affects all voices. 

EXAMPLES: 

VOL Sets volume to its lowest level. 

VOL 15 Sets volume for SOUND and PLAY statements to its highest 
output. 

— Pause program execution until a data condition is satisfied 

WAIT (Location), <mask-1 > [,mask-2>] 

The WAIT statement causes program execution to be suspended 
until a given memory address recognizes a specified bit pattern or 
value. In other words, WAIT can be used to halt the program until 
some external event has occurred. This is done by monitoring the 
status of bits in the Input/Output registers. The data items used with 
the WAIT can be any values. For most programmers, this statement 
should never be used. It causes the program to halt until a specific 
memory location's bits change in a specific way. This is used for 
certain I/O operations and almost nothing else. The WAIT statement 
takes the value in the memory location and performs a logical AND 
operation with the value in mask-1 . If mask-2 is specified, the result 
of the first operation is exclusively ORed with mask-2. In other words, 
mask-1 "filters out" any bits not to be tested. Where the bit is in 
mask-1 , the corresponding bit in the result will always be 0. The 
mask-2 value flips any bits, so that an off condition can be tested for 
as well as an on condition. Any bits being tested for a should have a 
1 in the corresponding position in mask-2. If corresponding bits of 
the < mask-1 > and <mask-2> operands differ, the exclusive-OR opera- 
tion gives a bit result of 1 . If the corresponding bits get the same 
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WIDTH 



WINDOW 



= 10010000 in binary and 16 = 
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result tine bit is 0. It is possible to enter an infinite pause with the 
WAIT statement, in which case the RUN/STOP and RESTORE keys 
can be used to recover. WAIT may require a BANK command if the 
memory you wish to access is not in the currently selected BANK. 

The first example below WAITs until a key is pressed on the tape unit 
to continue with the program. The second example will WAIT until a 
sprite collides with the screen background. 

EXAMPLES: 

WAIT 1, 32, 32 
WAIT 53273, 6, 6 
WAIT 36868, 144, 16 

(144 and 16 are binary masks. 144 
10000 in binary.) 

— Set the width of drawn lines 

WIDTH n 

This command sets the width of lines drawn using BASIC'S graphic 
commands to either single or double width. Giving n a value of 1 
defines a single width line; a value of 2 defines a double width line. 
EXAMPLES: 

WIDTH 1 Set single width for graphic commands 
WIDTH 2 Set double width for drawn lines 

— Defines a screen window 

WINDOW top left col,top left row,bot right col, hot right 
row[,clear] 

This command defines a logical window within the 40 or 80 column 
text screen. The coordinates must be in the range 0-39/79 for column 
values and 0-24 for row values screen. The clear flag, if provided (1), 
causes a screen-clear to be performed (but only within the limits of 
the newly described window). 

EXAMPLES: 

WINDOW 5,5,35,20 Defines a window with top left corner 

coordinate as 5,5 and bottom right corner 
coordinate as 35,20. 

WINDOW 10,2,33,24,1 Defines a window with upper left corner 
coordinate (10,2) and lower right corner 
coordinate (33,24). Also clears the portion of 
the screen with the window as specified by 
the 1. 
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SECTION 18 
BASIC Functions 
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Basic Functions 
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ABS 



ASC 



ATN 



The format of the function description is: 
FUNCTION (argument) 

where the argument can be a numeric value, variable or string. 

Each function description is followed by an EXAMPLE. The lines 
appearing in bold face in the examples are the functions you type in. 
The line without bold is the computer's response. 

— Return absolute value 

ABS (X) 

The absolute value function returns the positive value of the argu- 
ment X. 

EXAMPLE: 

PRINT ABS (7*(-5) ) 

35 

— Return CBM ASCII code for character 

ASC(X$) 

This function returns the ASCII code of the first character of X$. You 
no longer have to append CHR$(0) to a null string. ILLEGAL QUAN- 
TITY ERROR is no longer issued. 

EXAMPLE: 

X$ = C1 28:PRI NT ASC (X$) 

67 

— Return angle whose tangent is X radians 

ATN (X) 

This function returns the angle whose tangent is X, measured in radi- 
ans. 

EXAMPLE: 

PRINT ATN (3) 

1 .24904577 
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— Return sprite collision infornnation 

BUMP(N) 

To determine which sprites have collided since the last check, use 
the BUMP function. BUMP(1) records which sprites have collided 
with each other and BUMP(2) records which sprites have collided 
with other objects on the screen. COLLISION need not be active to 
use BUMP The bit positions (0-7) in the BUMP value correspond to 
sprites 1 through 8 respectively. BUMP(n) is reset to zero after each 
call. 

The value returned by BUMP is the result of two raised to the power 
of the bit position. Forexannple, if BUMP returned a value of 16, 
sprite 4 was involved in a collision since 2 raised to the fourth power 
equals 1 6. Here's how the sprite numbers and BUMP values 
returned correspond: 



BUMP Value: 128 


64 


32 


16 


8 


4 


2 


1 


Sprite Number: 7 


6 


5 


4 


3 


2 


1 
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EXAMPLES: 

PRINT BUMP (1) 

12 Indicates that sprite 2 and 3 have collided. 

PRINT BUMP (2) 

32 Indicates that sprite 5 has collided with an 

object on the screen. 
—Return ASCII character for specified CBM ASCII code 

CHR$(X) 

This is the opposite of ASC and returns the string character whose 
CBM ASCII code is X. Refer to Appendix E for a table of CHR$ codes. 

EXAMPLES: 

PRINT CHR$ (65) Prints the A character. 

A 

PRINT CHR$ (147) Clears the text screen. 



— Return cosine for angle of X radians 

COS(X) 

This function returns the value of the cosine of X, where X is an angle 
measured in radians. 

EXAMPLE: 

PRINT COS (ir/3) 

.500000001 
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— Return decimal value of hexadecimal number string 

DEC (hexadecimal-string) 

This function returns the decimal value of a character string repre- 
senting a hexadecimal number in the range 0-$FFFF (0-65535 
decimal). 

EXAMPLE: 

PRINT DEC ("D020") 

53280 
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— Return the string describing an error condition 

ERR$(N) 

This function returns a string describing an error condition. The 
range for N lies between 1 and 41 . Also see system variables EL and 
ER and Appendix A for a list of BASIC error messages. 

EXAMPLES: 

PRINT ERR$(20) 

DIVISION BY ZERO 

PRINT ERR$(38) 

LINE NUMBER TOO LARGE 
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— Return value of an approximation of e (2.71 8281 3) raised to the X 
power 

EXP(X) 

This function returns a value of e (2.718281 3) raised to the power of 
X. 

EXAMPLE: 

PRINT EXP(1) 

2.71828183 



FNxx 



n 
n 



— Return value from user defined function 

FNxx(x) 

This function returns the value f ronn the user-defined function xx 
created in a DEF FNxx statement. 
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HEX$ 



INSTR 
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10 DEF FNAA(X) = (X-32)*5/9 

20 INPUT X 

30 PRINT FNAA(X) 

RUN 

? 40 (? is input prompt) 
4.44444445 

NOTE: If GRAPHIC is used in a program that defines a function, issue 
the GRAPHIC command before defining the function, or else the 
function definition is destroyed. 

— Return nunnber of available bytes in mennory 

FRE(X) 

where X is the bank number. X = BASIC program storage and X = 1 
to check for available BASIC variable storage. 

EXAMPLES: 

PRINT FRE (0) Returns the number of free bytes for BASIC 
48893 programs. 

PRINT FRE 

(1) Returns the number of free bytes for BASIC 

64256 variable storage. 

— Return hexadecimal number string from decimal number 

HEX$(X) 

This function returns a four-character string containing the hexadeci- 
mal representation of value X ( < = X < = 65535). The decimal 
counterpart of this function is DEC. 

EXAMPLE: 

PRINT HEX$(53280) 

D020 

— Return position of string 1 in string 2 

INSTR (string 1 , string 2 [^starting position]) 

The INSTR function searches for the first occurrence of string 2 
within string 1 , and returns the position within the string where the 
match is found. The optional parameter for STARTING POSITION 
establishes the position in string 1 where the search begins. The 
STARTING POSITION must be in the range 1 through 255. If no 
match is found or, if the STARTING POSITION is greater than the 
length of string 1 or if string 1 is null, INSTR returns the value 0. If 
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string 2 is null, INSTR returns tlie value of the STARTING POSITION 
or the value 1. 

EXAMPLE: 

PRINT INSTR ("COMMODORE 128","128") 

11 

— Return integer form (truncated) of a floating point value 

INT(X) 

This function returns the integer value of the expression. If the 
expression is positive, the fractional part is left out. If the expression 
is negative, any fraction causes the next lower integer to be 
returned. 

EXAMPLES: 

PRINT INT(3.14) 

3 

PRiNTINT(-3.14) 

-4 



JOY 



n 

n 
n 
n 

I \ 

n 

) \ 



— Return position of joystick and the status of tlie fire button 
JOY(N) 

when N equals: 

1 JOY returns position of joystick 1. 

2 JOY returns position of joystick 2. 

Any value of 1 28 or nnore means that the fire button is also pressed. 
To find the JOY value, add the direction value of the joystick plus 1 28, 
if the fire button is pressed. The direction is indicated as follows: 



8 
6 



1 

5 



EXAMPLES: 



JOY (2) =135 

Joystick 2 fires to the left. 

IF (JOY (1) >127) = 128 THEN PRINT "FIRE". 

Determines whether the fire button is pressed. 
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— Return the leftmost characters of string 

LEFT$ (string,integer) 

This function returns a string connprised of the number of leftmost 
characters of the string determined by the specified integer. The 
integer argument must be in the range to 255. If the integer is 
greater than the length of the string, the entire string is returned. If 
an integer value of zero is used, then a null string (of zero length) is 
returned. 

EXAMPLE: 

PRINT LEFTS {"C0MM0D0RE",5) 

COM MO 



LEN 



— Return the length of a string 

LEN (string) 

This function returns the number of characters in the string expres- 
sion. Non-printed characters and blanks are included. 

EXAMPLE: 

PRINT LEN ("COMMODORE128") 

12 



LOG 



MID$ 
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— Return natural log of X 

LOG(X) 

This function returns the natural log of X. The natural log is log to the 
base e (see EXP(X)). To convert to log base 10, divide by LOG(IO). 

EXAMPLE: 

PRINT LOG (37/5) 

2.00148 



— Return a substring from a larger string 

MID$ (string,starting position[,length]) 

This function returns a substring specified by the LENGTH, starting 
at the character specified by the starting position. The starting posi- 
tion of the substring defines the first character where the substring 
begins. The length of the substring is specified by the length argue- 
ment. Both of the numeric arguments can have values ranging from 
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1 to 255. If the starting position value is greater than the length of the 
string, or if the length value is zero, then MID$ returns a null string 
value. If the length argument is left out, all characters to the right of 
the starting position are returned. You can assign a MID$ to a value 
with the equals sign. 

EXAMPLE: 

PRINT MID$("COMMODORE 128",3,5) 

MMODO 



PEEK 



n 

n 
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PEN 



— Return contents of a specified nriemory location 

PEEK(X) 

This function returns the contents of nnennory location X, where X is 
located in the range to 65535, returning a result between and 
255. This is the counterpart of the POKE statement. The data will be 
returned from the bank selected by the most recent BANK com- 
mand. See the BANK command. 

EXAMPLE: 

10 BANK 15:VIC = DEC("DOOO") 
20 FOR I = 1 TO 47 
30 PRINT PEEK(VIC + I) 
40 NEXT 

This example displays the contents of the registers of the VIC chip. 



— Return X and Y coordinates of the light pen 

PEN(n) 

where n = PEN returns the X coordinate of light pen position, 

n = 1 PEN returns the Y coordinate of light pen position, 

n = 2 PEN returns the X coordinate of the 80 column display 

n = 3 PEN returns the Y coordinate of the 80 column display 

n = 4 PEN returns the (80-column) light pen trigger value. 

Note that, like sprite coordinates, the PEN value is not scaled and 
uses real coordinates, not graphic bit map coordinates. The X posi- 
tion is given as an even number, ranging from approximately 60 to 
320, while the Y position can be any number from 50 to 250. These 
are the visible screen coordinate ranges, where all other values are 
not visible on the screen. A value of zero for either position means 
the light pen is off screen and has not triggered an interrupt since 
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POS 



the last read. Note that COLLISION need not be active to use PEN. A 
white background is usually required to stinnulate the light pen. PEN 
values vary f ronn CRT to CRT. 

Unlike the 40 colunnn (VIC) screen, the 80 colunnn (8563) coordinates 
are character row and column positions and not pixel coordinates 
like the VIC screen. Both the 40 and 80 colunnn screen coordinate 
values are approximate and vary due to the nature of light pens. The 
read values are not valid until PEN(4) is true. 

EXAMPLES: 

10 PRINT PEN(0);PEN(1) Displays the X and Y coordinates of 

the light pen (for the 40 colunnn 
screen). 

10 DO UNTIL PEN(4):L00P Ensures the read values are valid (for 

the 80 colunnn screen). 

20X = PEN(2) 

30Y = PEN{3) 

40 REM:REST OF PROGRAM 

—Return the value of pi (3.14159265) 

TT 

EXAMPLE: 

PRINT TT This returns the result 3.14159265. 

— Return the address of a variable nanne 
POINTER (variable name) 



EXAMPLE: 

A = POINTER (Z) 



This exannple returns the address of variable Z. 
(Address returned is in BANK 1.) 
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— Return the current cursor colunnn position within the current 
screen window 

POS(X) 

The POS function indicates where the cursor is within the defined 
screen window. X is a dunnmy argument, which must be specified, 
but the value is ignored. 

EXAMPLE: 

PRINT POS(0) 
10 
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This displays tine current cursor position witliin tlie defined text win- 
dow, in this case 10. 
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— Returns the value of the game-paddle potentiometer 
POT(n) 

when: 

n = 1, POT returns the position of paddle #1 
n = 2, POT returns the position of paddle #2 
n = 3, POT returns the position of paddle #3 
n = 4, POT returns the position of paddle #4 

The values for POT range from to 255. Any value of 256 or more 
means that the fire button is also depressed. 

EXAMPLE: 

10 PRINT P0T(1) 

20 IF P0T(1) > 256 THEN PRINT "FIRE" 

This example displays the value of the game paddle 1 . 



—Return color of color source 

RCLR(N) 

This function returns the color (1 through 1 6) assigned to the color 
source N (0< N < 6), where the following N values apply: 

= 40-column background 

1 = bit map foreground 

2 = multicolor 1 

3 = multicolor 2 

4 = 40-column border 

5 zz 40- or 80-column character color 

6 = 80-column background color 

The counterpart to the RCLR function is the COLOR command. 

EXAMPLE: 

10 FOR I = TO 6 

20 PRINT "SOURCE";l;"IS COLOR CODE";RCLR(l) 

30 NEXT 

This example prints the color codes for all seven color sources. 
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RGR 
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— Return current position or color source of pixel cursor 

RDOT (N) 

where: 

N = returns the X coordinate of the pixel cursor 

N = 1 returns the Y coordinate of the pixel cursor 

N = 2 returns the color source of the pixel cursor 

This function returns the location of the current position of the pixel 
cursor (PC) or the current color source of the pixel cursor. The 
returned coordinate value is affected by scaling, and will return the 
scaled coordinate value. 



EXAMPLES: 
PRINT RDOT(0) 
PRINT RD0T{1) 
PRINT RD0T(2) 



Returns X position of PC 
Returns Y position of PC 
Returns color source of PC 



— Return current graphic mode 

RGR(X) 

This function returns the current graphic nnode. X is a dunnmy argu- 
nnent, which must be specified. The counterpart of the RGR function 
is the GRAPHIC command. The value returned by RGR(X) pertains to 
the following modes: 



VALUE 


GRAPHIC MODE 





40 column (VIC) text 


1 


Standard bit map 


2 


Split screen bit map 


3 


Multicolor bit map 


4 


Split screen Multicolor bit map 


5 


80 column (8563) text 


EXAMPLE: 





PRINT RGR(0) Displays the current graphic mode; 
1 in this case, standard bit map mode. 

— Return sub-string from rightmost end of string 

RIGHT$« string), (numeric)) 

This function returns a sub-string taken from the rightmost charac- 
ters of the string argument. The length of the sub-string is defined by 
the length argument which can be any integer in the range of to 
255. If the value of the numeric expression is zero, then a null string 
is returned. If the value given in the length argument is greater than 
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the length of the string, the entire string is returned. Also see the 
LEFTS and MID$ functions. 

EXAMPLE: 

PRINT RIGHT$("BASEBALL",5) 

EBALL 



— Return a randonn number 

RND(X) 

This function returns a random number between and 1 . This is use- 
ful in games, to simulate dice roll and other elements of chance. It is 
also used in some statistical applications. 

If X = RND returns a random number based on the hardware 

clock. 
If X > 1 RND generates a reproducible psuedo-random number 

based on the seed value below. 
If X < produces a random number which is used as a base 

called a seed. 

To simulate the rolling of a die, use the formula INT(RND(1)*6 + 1). 
First the random number from to 1 is multiplied by 6, which 
expands the range to 0-6 (actually, greater than zero and less than 
six). Then 1 is added, making the range greater than 1 and less than 
7. The INT function truncates all the decimal places, leaving the 
result as a digit from 1 to 6. 

EXAMPLES: 



PRINT RND(0) 

.507824123 

PRINT INT(RND{1)*100 

89 



Displays a random number 
between and 1. 
1) Displays a random number 
between 1 and 100. 



— Return sprite multicolor values 
RSPCOLOR (register) 

When: 

X = 1 RSPCOLOR returns the sprite multicolor 1. 
X = 2 RSPCOLOR returns the sprite multicolor 2. 

The returned color value is a value between 1 and 16. The counter- 
part of the RSPCOLOR function is the SPRCOLOR statement. Also 
see the SPRCOLOR statement. 



/ \ 
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EXAMPLE: 

10 SPRITE 1,1,2,0,1,1,1 

20 SPRCOLOR 5,7 

30 PRINT"SPRITE MULTICOLOR 1 IS";RSPC0L0R(1) 

40 PRINT"SPRITE MULTICOLOR 2 IS";RSPC0L0R(2) 

RUN 

SPRITE MULTICOLOR 1 IS 5 
SPRITE MULTICOLOR 2 IS 7 

In this example line 1 turns on sprite 1 , colors it white, expands it in 
both the X and Y directions and displays it in nnulticolor mode. Line 
20 selects sprite multicolors 1 and 2. Lines 30 and 40 print the RSP- 
COLOR values for multicolor 1 and 2. 



— Return the speed and position values of a sprite 

RSPPOS (sprite number,position/speed) 

where sprite number identifies which sprite is being checked, and 
position and speed specifies X and Y coordinates or the sprite's 
speed. 

When position equals: 

RSPPOS returns the current X position of the specified sprite. 

1 RSPPOS returns the current Y position of the specified sprite. 

When speed equals: 

2 RSPPOS returns the speed (0-15) of the specified sprite. 

EXAMPLE: 

10 SPRITE 1,1,2 

20 MOVSPR 1,45#13 

30 PRINT RSPPOS (1,0);RSPPOS (1,1);RSPP0S (1,2) 

This example returns the current X and Y sprite coordinates and the 
speed (1 3). The returned coordinate value is affected by scaling. If 
scaling is enabled, the returned coordinate is proportional to the 
specified scaled coordinates. 



— Return sprite characteristics 

RSPRITE (sprite number,characteristic) 

RSPRITE returns sprite characteristics that were specified in the 
SPRITE command. Sprite number specifies the sprite you are check- 
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RWINDOW 



ing and the characteristic specifies the sprite's display qualities as 
follows: 



Characteristic 


1 
2 



3 
4 
5 



RSPRITE returns 
these values: 

Enabled(1)/disabled(0) 
Sprite color (1-16) 
Sprites are displayed in front 
of (0) or behind (1) objects 
on the screen 
Expand in X direction 
Expand in Y direction 
Multicolor 



yes = 1 , no = 
yes = 1 , no = 
yes = 1 , no = 



EXAI\APLE: 



10 FOR I = TO 5 
20 PRINT RSPRITE (1,1) 
30 NEXT 



This example prints all 5 
characteristics of sprite 1 . 



— Returns the size of the current window 
RWINDOW (n) 

When n equals: 

RWINDOW returns a value one less than the number of lines in 
the current window. 

1 RWINDOW returns a value one less than the number of rows in 
the current window. 

2 RWINDOW returns either of the values 40 or 80, depending on 
the current screen output format you are using. 

The counterpart of the RWINDOW function is the WINDOW 
connmand. 

EXAMPLE: 

10 WINDOW 1,1,10,10 

20 PRINT RWINDOW(0);RWINDOW(1);RWINDOW(2) 

RUN 

9 9 40 
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— Return sign of argument X 

SGN(X) 

This function returns the sign,(positive, negative or zero) of X. The 
result is + 1 if X > 0, if X = 0, and - 1 if X < 0. 

EXAMPLE: 

PRINT SGN(4.5);SGN(0);SGN(-2.3) 

1 -1 



— Return sine of argument 

SIN(X) 

This is the trigonometric sine function. The result is the sine of X. X is 
measured in radians. 

EXAMPLE: 

PRINT SIN (tt/S) 

.866025404 



— Sl<ip spaces on the screen 

SPC (X) 

This function is used in PRINT or PRINTf commands to control the 
formatting of data, as either output to the screen or output to a logi- 
cal file. The number of SPaCes specified by X determines the num- 
ber of characters to fill with spaces across the screen or in a file. For 
screen or tape files, the value of the argument is in the range to 
255 and for disl< files the maximum is 254. For printer files, an auto- 
matic carriage-return and line-feed \n\\\ be performed by the printer if 
a SPaCe is printed in the last character position of a line. No SPaCes 
are printed on the following line. 

EXAMPLE 

PRINT "COMMODORE";SPC(3);"128" 

COMMODORE 128 
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— Return square root of argument 

SQR(X) 

This function returns the value of the SQuare Root of X, where X is a 
positive nunnber or 0. The value of the argunnent must not be nega- 
tive, or the BASIC error message 7ILLEGAL QUANTITY is displayed. 

EXAMPLE: 
PRINT SQR(25) 

5 



— Return string representation of number 

STR$ (X) 

This function returns the STRing representation of the numeric value 
of the argument X. When the STR$ value is converted to each varia- 
ble represented in the argument, any number displayed is preceded 
and followed by a space except for negative numbers which are pre- 
ceded by a minus sign. The counterpart of the STR$ function is the 
VAL function. 

EXAMPLE 

PRINT STR$(123.45) 

123.45 

PRINT STR$(- 89.03) 

-89.03 

PRINT STR$(1E20) 

1E + 20 



— Moves cursor to tab position in present statement 

TAB(X) 

This function moves the cursor forward if possible to a relative posi- 
tion on the text screen given by the argument X, starting with the left- 
most position of the current line. The value of the argument can 
range from to 255. If the current print position is already beyond 
position X, TAB places the cursor in the X position in the next line. 
The TAB function can only be used with the PRINT statement, since 
it has no effect if used with the PRINT# to a logical file. 

EXAMPLE: 

10 PRINT"COMMODORE"TAB(25)"128" 

COMMODORE 128 
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— Return tangent of arguennent 
TAN(X) 

This function returns tine tangent of X, wlnere X is an angle in radians. 
EXAMPLE: 

PRINT TAN(.785398163) 

1 



— Call user-defined subprogram 

USR(X) 

When this function is used, the program jumps to a machine lan- 
guage program whose starting point is contained in memory loca- 
tions 4633($1219) and 4634($121A), (and 785($031 1) and 786($0312) 
for C64 mode). The parameter X is passed to the machine-language 
program in the floating point accumulator. A value is returned to the 
BASIC program through the calling variable. You must redirect the 
value into a variable in your program in order to receive the value 
back from the floating point accumulator. An ILLEGAL QUANTITY 
ERROR results if you don't specify this variable. This allows the user 
to exchange a variable between machine code and BASIC. 

EXAMPLE: 

10 POKE 4633,0 
20 POKE 4634,192 
30 A = USR(X) 
40 PRINT A 

Place Starting location ($0000 = 491 52:$00 = 0:$C0= 192) of 
machine language routine in location 4633 and 4634. Line 30 stores 
the returning value from the floating point accumulator. 



— Return the numeric value of a number string 

VAL(X$) 

This function converts the string X$ into a number which is the 
inverse operation of STR$. The string is examined from the left-most 
character to the right, for as many characters as are in recognizable 
number format. If the Commodore 128 finds illegal characters, only 
the portion of the string up to that point is converted. If no numeric 
characters are present, VAL returns a 0. 
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EXAMPLE: 

10 A$ = "120" 

20 B$ = "365" 

30 PRINT VAL A$ + VAL B$ 

RUN 

485 



— Return exclusive OR 

XOR(n1,n2) 

This function provides the exclusive OR of the argument values n1 
and n2. 

X = XOR (n1,n2) 

where n1 , n2, are 2 unsigned values (0-65535). 
EXAMPLE: 

PRINT XOR(128,64) 

192 
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SECTION 19 

VarSaEsles and 
Operators 



VARIABLES 
OPERATORS 
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The Commodore 128 uses three types of variables in BASIC. These 
are: normal numeric, integer numeric and string (alphanumeric). 

Normal NUMERIC VARIABLES, also called floating point variables, 
can have any value from **superscript** - 10 to **super- 
script* * + 1 0, with up to nine digits of accuracy. When a number 
becomes larger than nine digits can show, as in + 10 or - 10, the 
computer displays it in scientific notation form, with the number nor- 
malized to one digit and eight decimal places, followed by the letter E 
and the power of 1 by which the number is multiplied. For example, 
the number 1 2345678901 is displayed as 1 .23456789E + 1 0. 

INTEGER VARIABLES can be used when the number is from 
+ 32767 to - 32768, and with no fractional portion. Ap integer varia- 
ble is a number like 5, 1 or - 1 00. Integers take up less space than 
floating point variables, particularly when used in an array 

STRING VARIABLES are those used for character data, which may 
contain numbers, letters and any other characters the Commodore 
1 28 can display An example of a string variable is "Commodore 
128." 

VARIABLE NAMES may consist of a single letter, a letter followed by 
a number or two letters. Variable names may be longer than two 
characters, but only the first two are significant. An integer is speci- 
fied by using the percent sign (%) after the variable name. String 
variables have a dollar sign ($) after their names. 

EXAMPLES: 

Numeric Variable Names: A, AS, BZ 
Integer Variable Names: A%, A5%, BZ% 
String Variable Names: A$, A5$, BZ$ 

ARRAYS are lists of variables with the same name, using an extra 
number (or numbers) to specify an element of the array Arrays are 
defined using the DIM statement and may be floating point, integer 
or string variable arrays. The array variable name is followed by a set 
of parentheses () enclosing the number of the variable in the list. 

EXAMPLE: 

A(7), BZ%(11), A$(87) 

Arrays can have more than one dimension. A two-dimensional array 
may be viewed as having rows and columns, with the first number 
identifying the row and the second number identifying the column 
(as if specifying a certain grid on a map). 
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EXAMPLE: 

A(7,2), BZ%(2,3,4), Z$(3,2) 



EXAMPLE: 

Tl$ = "101530" Sets the clock to 10:15 and 30 seconds (AM). 

The value of the clock is lost when the Connmodore 1 28 is turned off. 
It starts at zero when the Connnnodore 1 28 is turned on, and is reset 
to zero when the value of the clock exceeds 235959 (23 hours, 59 
minutes and 59 seconds). 



ER, EL and ERR$ are variables used in error trapping routines. They 
are usually only useful within a program. ER returns the last error 
encountered since the program was RUN. EL is the line where the 
error occurred. ERR$ is a function that allows the program to print 
one of the BASIC error messages. PRINT ERR$(ER) prints out the 
proper error message. 
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RESERVED VARIABLE NAMES are names reserved for use by the j 

Commodore 1 28, and may not be used for another purpose. These | 1 

are the variables DS, DS$, ER, ERR$, EL, ST Tl and Tl$. KEYWORDS 

such as TO and IF or any other names that contain KEYWORDS, 

such as RUN, NEW or LOAD cannot be used. |_t 

ST is a status variable for input and output (except normal screen/ 

keyboard operations). The value of ST depends on the results of the \ ( 

last I/O operation. In general, if the value of ST is 0, then the opera- 
tion was successful. 

Li 

Tl and Tl$ are variables that relate to the real time clock built into the 
Commodore 128. The system clock is updated every 1/60th of a sec- 
ond. It starts at when the Commodore 1 28 is turned on, and is j \ 

reset only by changing the value of Tl$. The variable Tl gives the cur- 
rent value of the clock in 1/60th of a second. Tl$ is a string that reads 

the value of the real time clock as a 24-hour clock. The first two char- | \ 

acters of Tl$ contain the hour, the third and fourth characters are 
minutes and the fifth and sixth characters are seconds. This variable 

can be set to any value (so long as all characters are numbers) and j j 

will be updated automatically as a 24-hour clock. 



u 
u 
u 

The variable DS reads the disk drive command channel and returns 

the current status of the drive. To get this information in words, i i 

PRINT DS$. These status variables are used after a disk operation, I — i 

like DLOAD or DSAVE, to find out why the red error light on the disk 

drive is blinking. 



u 
u 
u 
u 

u 
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Operators 
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n 
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The BASIC OPERATORS include ARITHMETIC, RELATIONAL and 
LOGICAL OPERATORS. The ARITHMETIC operators include the fol- 
lowing signs: 

+ addition 

- subtraction 

* multiplication 

/ division 

t raising to a power (exponentiation) 

On a line containing nnore than one operator, there is a set order in 
which operations always occur. If several operators are used 
together, the connputer assigns priorities as follows: First, exponen- 
tiation, then nnultiplication and division, and last, addition and sub- 
traction. If two operators have the sanne priority, then calculations 
are performed in order f ronn left to right. If these operations are to 
occur in a different order. Commodore 128 BASIC allows giving a 
calculation a higher priority by placing parentheses around it. Opera- 
tions enclosed in parentheses will be calculated before any other 
operation. Make sure the equations have the same number of left 
and right parentheses, or a SYNTAX ERROR message is posted 
when the program is run. 

There are also operators for equalities and inequalities, called RELA- 
TIONAL operators. Arithmetic operators always take priority over 
relational operators. 

= is equal to 

< is less than 

> is greater than 

< = or ^ < is less than or equal to 

> = or = > is greater than or equal to 
<> or X is not equal to 

Finally there are three LOGICAL operators, with lower priority than 
both arithmetic and relational operators: 

AND 

OR 

NOT 

These are most often used to join multiple formulas in IF ... THEN 
statements. When they are used with arithmetic operators, they are 
evaluated last (i.e., after + and - ). If the relationship stated in the 
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expression is true, the result is assigned an integer value of - 1 . If 
false, a value of is assigned. 



EXAMPLES: 

IF A=B ANDC = DTHEN 100 

IFA=BORC = DTHEN 100 

A = 5:B = 4:PRINTA=B 
A = 5:B = 4:PRINTA>3 
PRINT123AND15:PRINT5 
OR 7 



Requires both A= B & C = D 

to be true. 

Allows either A= B or C = D 

to be true. 

Displays a value of 0. 

Displays a value of - 1 . 

Displays 1 1 and 7. 
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SECTION 20 
Reserved Words 
and Symbols 



RESERVED SYSTEM WORDS (KEYWORDS) 
RESERVED SYSTEM SYMBOLS 
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Reserved System 
Words (Keywords) 



This section lists the words and symbols used to make up the BASIC 
7.0 language. These words and symbols cannot be used within a 
program as other than a component of the BASIC language. The only 
exception is that they may be used within quotes in a PRINT state- 
ment. 



ABS 


DIM 


HEADER 


PRINT 


SPRCOLOR 


AND 


DIRECTORY 


HELP 


PRINT USING 


SPRDEF 


APPEND 


DLOAD 


HEX$ 


PRINT# 


SPRITE 


ASC 


DO 


IF 


PRINT# USING 


SPRSAV 


ATN 


DOPEN 


INPUT 


PUDEF 


SQR 


AUTO 


DRAW 


INPUT# 


QUIT 


ST 


BACKUP 


DS 


INSTR 


RCLR 


STASH 


BANK 


DSAVE 


INT 


RDOT 


STEP 


BEGIN 


DS$ 


JOY 


READ 


STOP 


BEND 


DVERIFY 


KEY 


RECORD 


STRS 


BLOAD 


EL 


LEFTS 


RENAME 


SWAP 


BOOT 


ELSE 


LEN 


RENUMBER 


SYS 


BOX 


END 


LET 


RESTORE 


TAB 


BSAVE 


ENVELOPE 


LIST 


RESUME 


TAN 


BUMP 


ER 


LOAD 


RETURN 


TEMPO 


CHAR 


ERRS 


LOCATE 


RGR 


THEN 


CHR$ 


EXIT 


LOG 


RIGHTS 


Tl 


CIRCLE 


EXP 


LOOP 


RND 


TIS 


CLOSE 


FAST 


MIDS 


RSPCOLOR 


TO 


CLR 


FETCH 


MONITOR 


RSPPOS 


TRAP 


CMD 


FILTER 


MOVSPR 


RSPRITE 


TRON 


COLLECT 


FN 


NEW 


RUN 


TROFF 


COLOR 


FOR 


NEXT 


RWINDOW 


UNTIL 


CONCAT 


FRE 


NOT 


SAVE 


USR 


CONT 


GET 


OFF 


SCALE 


VAL 


COPY 


GETKEY 


ON 


SCNCLR 


VERIFY 


COS 


GET# 


OPEN 


SCRATCH 


VOL 


DATA 


G064 


OR 


SGN 


WAIT 


DCLEAR 


GOSUB 


PAINT 


SIN 


WHILE 


DOLOSE 


GOTO 


PEN 


SLEEP 


WIDTH 


DEC 


GOTO 


PLAY 


SLOW 


WINDOW 


DEFFN 


GRAPHIC 


PCS 


SOUND 


XOR 


DELETE 


GSHAPE 


POT 


SPC 





333 



BASIC 7.0 ENCYCLOPEDIA— Reserved Words and Symbols 



Reserved System 
Symbols 



The following characters are reserved system symbols. 



Symbol 

+ Plus sign movement 



- Minus sign 
movement 

* Asterisk 

/ Slash 

t Up arrow 

Blank space 

= Equal sign 

< Less than 

> Greater than 

, Comma 

Period 

; Semicolon 

Colon 

"" Quotation mark 

? Question mark 

( Left parenthesis 

) Right parenthesis 

% Percent 



# Number 

$ Dollar sign 

& And sign 

IT Pi 



Use(s) 

Arithmetic addition; string concatenation; 

relative Pixel Cursor/sprite movement; 

declare decimal number in machine 

language monitor 

Arithmetic subtraction; negative number; 

unary minus; relative pixel cursor/ sprite 

movement 

Arithmetic multiplication 

Arithmetic division 

Arithmetic exponentiation 

Separate keywords and variable names 

Value assignment; relationship testing 

Relationship testing 

Relationship testing 

Format output in variable lists; command/ 

statement function parameters 

Decimal point in floating point constants 

Format output in variable lists 

Separate multiple BASIC statements on a 

program line 

Enclose string constants 

Abbreviation for the keyword PRINT 

Expression evaluation and functions 

Expression evaluation and functions 

Declare a variable name as integer; 

declare binary number in machine 

language monitor 

Precede the logical file number in input/ 

output statements 

Declare a variable name as a string and 

declares hexadecimal number in 

machine language monitor 

Declare octal number in machine 

language monitor 

Declare the numeric constant 

3.141592654 
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APPENDIX A — BASIC LANGUAGE ERROR MESSAGES 

APPENDIX B — DOS ERROR MESSAGES 

APPENDIX — CONNECTORS/PORTS FOR PERIPHERAL 

EOUIPMENT 

APPENDIX D — SCREEN DISPLAY CODES 

APPENDIX E — ASCII AND CHR$ CODES 

APPENDIX F — SCREEN AND COLOR MEMORY MAPS 
APPENDIX G — DERIVED MATHEMATICAL FUNCTIONS 

APPENDIX H — MEMORY MAP 

APPENDIX I — CONTROL AND ESCAPE CODES 

APPENDIX J — MACHINE LANGUAGE MONITOR 

APPENDIX K — BASIC 7.0 ABBREVIATIONS 

APPENDIX L — DISK COMMAND SUMMARY 
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ERBOn 
StffiESSAGES 


The following error messages are displayed by BASIC. Error mes- 
sages can also be displayed with the use of the ERR$() function. The 
error numbers below refer only to the number assigned to the error 
for use with the ERR$() function. 


1 — 1 




ERROR # 


ERROR NAME 


DESCRIPTION 




1 


TOO MANY FILES 


There is a limit of 10 files 
OPEN at one time. 




2 


FILE OPEN 


An attempt was made to open 
a file using the number of an 
already open file. 


n 




3 


FILE NOT OPEN 


The file number specified in an 
I/O statement must be opened 
before use. 


n 

n 

1 




4 
5 


FILE NOT FOUND 
DEVICE NOT PRESENT 


Either no file with that name 
exists (disk) or an end-of-tape 
marker was read (tape). 

The required I/O device is not 
available or buffers dealloca- 
ted (cassette). Check to make 
sure the device is connected 
and turned on. 




6 


NOT INPUT FILE 


An attempt was made to GET 
or INPUT data from a file that 
was specified as output only. 


— 1 




7 


NOT OUTPUT FILE 


An attempt was made to send 
data to a file that was speci- 
fied as input only 


n 




8 


MISSING FILE NAME 


File name missing in 
command. 


■"^ 




9 


ILLEGAL DEVICE 
NUMBER 


An attempt was made to use a 
device improperly (SAVE to 
the screen, etc.). 












1 — I 










n 
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5S 



10 



11 



12 



13 



14 



15 



16 



17 
18 



NEXT WITHOUT FOR 



SYNTAX 



RETURN WITHOUT 
GOSUB 



OUT OF DATA 



ILLEGAL QUANTITY 



OVERFLOW 



OUT OF MEMORY 



UNDEF'D STATEMENT 
BAD SUBSCRIPT 



19 



REDIM'D ARRAY 



Either loops are nested incor- 
rectly, or there is a variable 
name in a NEXT statement 
that doesn't correspond with 
one in FOR. 

A statement not recognized by 
BASIC. This could be because 
of a missing or extra parenthe- 
sis, misspelled keyword, etc. 

A RETURN statement was en- 
countered when no GOSUB 
statement was active. 

A READ statement encoun- 
tered without data left 
unREAD. 

A number used as the argu- 
ment of a function or state- 
ment is outside the allowable 
range. 

The result of a computation is 
larger than the largest number 
allowed (1.701 41 1834E + 38). 

Either there is no more room 
for program code and/or pro- 
gram variables, or there are 
too many nested DO, FOR or 
GOSUB statements in effect. 

A line number referenced 
doesn't exist in the program. 

The program tried to reference 
an element of an array out of 
the range specified by the DIM 
statement. 

An array can only be DIMen- 
sioned once. 
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20 


DIVISION BY ZERO 


Division by zero is not allowed. 


21 


ILLEGAL DIRECT 


INPUT GET INPUT #, GET # 
and GETKEY statennents are 
only allowed within a program. 


22 


TYPE MISMATCH 


This occurs when a numeric 
value is assigned to a string 
variable or vice versa. 


23 


STRING TOO LONG 


A string can contain up to 255 
characters. 


24 


FILE DATA 


Bad data read from a tape or 
disk file. 


25 


FORMULA TOO 
COMPLEX 


The computer was unable to 
understand this expression. 
Simplify the expression (break 
into two parts or use fewer 
parentheses). 



26 



CAN'T CONTINUE 



n 



I 1 



n 



27 

28 

29 
30 



UNDEF'D FUNCTION 



VERIFY 



LOAD 
BREAK 



The CONT command does not 
work if the program was not 
RUN, there was an error, or a 
line has been edited. 

A user-defined function was 
referenced that was never 
defined. 

The program on tape or disk 
does not match the program in 
memory 

There was a problem loading. 
Try again. 

The STOP command was 
issued in a program or the 
stop key was pressed to halt 
program execution. 



f 1 



\ \ 



n 
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31 


CANT RESUME 


A RESUME statement was 
encountered without a TRAP 
statennent in effect. 




32 


LOOP NOT FOUND 


The program has encountered 
a DO statement and cannot 
find the corresponding LOOP 


.-J 


33 


LOOP WITHOUT DO 


LOOP was encountered with- 
out a DO statement active. 


M 


34 


DIRECT MODE ONLY 


This command is allowed only 
in direct mode, not from a 
program. 


U 


35 


NO GRAPHICS AREA 


A command (DRAW, BOX, 
etc.) to create graphics was 
encountered before the 
GRAPHIC command was 
executed. 





36 


BAD DISK 


An attempt failed to HEADER 
a diskette, because the quick 
header method (no ID) was 
attempted on an unformatted 
diskette or the diskette is bad. 


I 


37 


BEND NOT FOUND 


The program encountered an 
"IF... THEN BEGIN" or "IF 
...THEN... ELSE BEGIN" 
construct, and could not find a 
BEND keyword to match the 
BEGIN. 


U 


38 


LINE NUMBER 
TOO LARGE 


An error has occurred in 
renumbering a BASIC pro- 
gram. The given parameters 
result in a line number > 
63999 being generated; there- 
fore, the renumbering was not 
performed. 


1 
1 1 
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39 



UNRESOLVED 
REFERENCE 



40 
41 



UNIMPLEMENTED 
COMMAND 

FILE READ 



An error has occurred in 
renumbering a BASIC pro- 
grann. A line nunnber referred 
to by a connnaand (e.g., GOTO 
999) does not exist. Therefore, 
the renumbering was not 
performed. 

A command not supported by 
BASIC 7.0 was encountered. 

An error condition was 
encountered while loading or 
reading a program or file from 
the disk drive (e.g., opening 
the disk drive door while a 
program was loading). 



1 _1 

n 



341 



APPENDIX A— Basic Language Error Messages 



u 
u 
u 
u 
u 
u 
u 
u 
u 
u 
u 
u 
u 
u 
u 
u 
u 
u 



APPENDIX B 
DOS ERROR 
MESSAGES 



f \ 



i 1 



( \ 



/ i 



f i 



I \ 



I i 



I \ 



t ) 



The following DOS error messages are returned through the DS and 
DS$ variables. The DS variable contains just the error number and 
the DS$ variable contains the error number, the error message, and 
any corresponding track and sector number. NOTE: Error message 
numbers less than 20 should be ignored with the exception of 01 , 
which gives information about the number of files scratched with the 
SCRATCH command. 

ERROR ERROR MESSAGE AND 
NUMBER DESCRIPTION 

20 READ ERROR (block header not found) 

The disk controller is unable to locate the header of the 
requested data block. Caused by an illegal sector num- 
ber, or the header has been destroyed. 

21 READ ERROR (no sync character) 

The disk controller is unable to detect a sync mark on 
the desired track. Caused by misalignment of the read/ 
write head, no diskette is present, or unformatted or 
improperly seated diskette. Can also indicate a hard- 
ware failure. 

22 READ ERROR (data block not present) 

The disk controller has been requested to read or verify 
a data block that was not properly written. This error 
occurs in conjunction with the BLOCK commands and 
can indicate an illegal track and/or sector request. 

23 READ ERROR (checksum error in data block) 

This error message indicates there is an error in one or 
more of the data bytes. The data has been read into the 
DOS memory but the checksum over the data is in error. 
This message may also indicate hardware grounding 
problems. 

24 READ ERROR (byte decoding error) 

The data or header has been read into the DOS memory 
but a hardware error has been created due to an invalid 
bit pattern in the data byte. This message may also indi- 
cate hardware grounding problems. 
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25 WRITE ERROR (write-verify error) Ij 
This message is generated if the controller detects a ^ — ' 
mismatch between the written data and the data in the 

DOS memory. j ; 

26 WRITE PROTECT ON 

This message is generated when the controller has been j ) 

requested to write a data block while the write protect ' — ^ 
switch is depressed. This is caused by using a diskette 

with a write protect tab over the notch or a notchless | i 

diskette. ^ 



27 READ ERROR 

This message is generated when a checksum error has 
been detected in the header of the requested data 
block. The block has not been read into DOS memory 

28 WRITE ERROR 

This error message is generated when a data block is 
too long and overwrites the sync mark of the next 
header. 

29 DISK ID MISMATCH 

This message is generated when the controller has been 
requested to access a diskette which has not been ini- 
tialized or improperly formatted. The message can also 
occur if a diskette has a bad header. 

30 SYNTAX ERROR (general syntax) 

The DOS cannot interpret the command sent to the 
command channel. Typically this is caused by an illegal 
number of file names, or patterns are illegally used. For 
example, two file names appear on the left side of the 
COPY command. 

31 SYNTAX ERROR (invalid command) 

The DOS does not recognize the command. The com- 
mand must start in the first position. 

32 SYNTAX ERROR (invalid command) 

The command sent is longer than 58 characters. Use 
abbreviated disk commands. 



u 
u 
u 
u 
u 
u 
u 
u 
u 



33 SYNTAX ERROR (invalid file name) U 

Pattern matching is invalidly used in tlie OPEN or SAVE 
command. Spell out tlie file name. , , 
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34 SYNTAX ERROR (no file given) 

The file nanne was left out of the command or the DOS 
does not recognize it as such. Typically, a colon (:) has 
been left out of the command. 

39 SYNTAX ERROR (invalid command) 

This error may result if the command sent to the com- 
mand channel (secondary address 15) is unrecognized 
by the DOS. 

50 RECORD NOT PRESENT 

Result of disk reading past the last record through 
INPUT# or GET# commands. This message will also 
occur after positioning to a record beyond end-of-f lie in a 
relative file. If the intent is to expand the file by adding 
the new record (with a PRINT# command), the error 
message may be ignored. INPUT* and GET # should 
not be attempted after this error is detected without first 
repositioning. 

51 OVERFLOW IN RECORD 

PRINT* statement exceeds record boundary Informa- 
tion is truncated. Since the carriage return which is sent 
as a record terminator is counted in the record size, this 
message will occur if the total characters in the record 
(including the final carriage return) exceeds the defined 
size of the record. 

52 FILE TOO LARGE 

Record position within a relative file indicates that disk 
overflow will result. 

60 WRITE FILE OPEN 

This message is generated when a write file that has not 
been closed is being opened for reading. 

61 FILE NOT OPEN 

This message is generated when a file is being 
accessed that has not been opened in the DOS. Some- 
times, in this case, a message is not generated; the 
request is simply ignored. 

62 FILE NOT FOUND 

The requested file does not exist on the indicated drive. 
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63 FILE EXISTS IJ 
The file name of the file being created already exists on 

the diskette. 

64 FILE TYPE MISMATCH ^ 
The requested file access is not possible using files of 

the type nanned. Reread the chapter covering that file ] ! 

type. 

65 NO BLOCK j J 
Occurs in conjunction with Block Allocation. The sector 

you tried to allocate is already allocated. The track and 

sector numbers returned are the next higher track and j 1 

sector available. If the track number returned is zero (0), 

all remaining higher sectors are full. If the diskette is not 

full yet, try a lower track and sector. | ) 

66 I LLEG AL TRACK AN D SECTOR 

The DOS has attempted to access a track or block | j 

which does not exist in the format being used. This may ^— ^ 

indicate a problem reading the pointer to the next block. 

67 I LLEG AL SYSTEM T OR S ^ 
This special error message indicates an illegal system 

track or sector. ] / 



70 NO CHANNEL (available) 

The requested channel is not available, or all channels 
are in use. A maximum of five buffers are available for 
use. A sequential file requires two buffers; a relative file 
requires three buffers; and the error/command channel 
requires one buffer. You may use any combination of 
those as long as the combination does not exceed five 
buffers. 



u 
u 
u 

71 DIRECTORY ERROR 

The BAM (Block Availability Map) on the diskette does \ ( 

not match the copy on disk memory To correct, initialize ' — ' 
the disk drive. 



72 DISK FULL 

Either the blocks on the diskette are used or the direc- 
tory is at its entry limit. DISK FULL is sent when two 
blocks are still available on the diskette, in order to allow 
the current file to be closed. 
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73 DOS VERSION NUMBER (73, CBM DOS V30 1 571 . 
00, 00) 

DOS 1 and 2 are read compatible but not write compat- 
ible. Disks may be interchangeably read with either 
DOS, but a disk formatted on one version cannot be 
written upon with the other version because the format 
is different. This error is displayed whenever an attempt 
is made to write upon a disk which has been formatted 
in a non-compatible format. This message will also 
appear after power-up or reset and is not an error in 
this case. 

74 DRIVE NOT READY 

An attempt has been made to access the disk drive 
without a diskette inserted; or the drive lever or door is 
open. 
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APPENDIX C 
CONNECTORS/ 
PORTS FOR 
PERIPHERAL 
EQUIPMENT 



COMMODORE CONNECTIONS FOR PERIPHERALS 





1 . Power Socket 

2. Power Switch 

3. Reset Button 

4. Controller Ports 

5. Expansion Port 

6. Cassette Port 



7. Serial Port 

8. Connposite Video/Audio Port 

9. Channel Selector 

10. RF Connector 

1 1 . RGBI Connector 

12. User Port 
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Side Panel 
Connections 



1 . Power Socket— The free end of the cable from the power supply 
is attached here. 

2. Power Switch— Turns on power f ronn the transformer. 

3. Reset Button — Resets computer (warm start). 

4. Controller Ports— There are two Controller ports, numbered 1 
and 2. Each Controller port can accept a joystick or game con- 
troller paddle. A light pen can be plugged only into port 1 , the 
port closest to the front of the computer. Use the ports as 
instructed with the software. 



Control Port 1 



Pin 

1 


Type 

JOYAO 


Note 


2 


JOYAl 




3 


JOYA2 




4 


JOYA3 




5 


POT AY 




6 


BUTTON A/LP 




7 


+ 5V 


MAX. 50mA 


8 


GND 




9 


POT AX 






(front view of port) 



Control Port 2 



Pin 

1 


Type 

JOYBO 


Note 


2 


JOYBl 




3 


JOYB2 




4 


JOYB3 




5 


POT BY 




6 


BUTTON B 




7 


+ 5V 


AAAX. 50mA 


8 


GND 




9 


POT BX 





u 
u 

Li 
LJ 
U 
U 
U 
U 
U 
U 
LI 
U 
U 
LJ 
U 
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Rear Connections 
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5. Expansion Port— This rectangular slot is a parallel port that 
accepts progrann or ganne cartridges as well as special 
interfaces. 



Cartridge Exponsion Slot 



Pin 


Type 


12 


BA 


13 


DMA 


14 


07 


15 


D6 


16 


05 


17 


D4 


18 


D3 


19 


D2 


20 


Dl 


21 


DO 


22 


GND 



Pin 


Type 


N 


A9 


P 


A8 


R 


A7 


S 


A6 


T 


A5 


U 


A4 


V 


A3 


w 


A2 


X 


Al 


Y 


AO 


z 


GND 



22 2120 1918 17 161514 13 12 1110 9 8 7 6 5 4 3 2 1 



2Y XWVUTSRPNMLKJHFEDCBA 

(view of port from the back of the C128) 



Pin 


Type 


1 


GND 


2 


+ 5V 


3 


+ 5V 


4 
5 


IRQ 
R/W 


6 


Dot Clock 


7 


I/O 1 


a 


GAME 


9 


EXROM 


10 
11 


I/O 2 
ROML 



Pin 


Type 


A 


GND 


B 


ROMH 


C 


RESET 


D 


NMI 


E 


S 02 


F 


A15 


H 


A14 


J 


A13 


K 


A12 


L 


All 


M 


AlO 
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6. Cassette Port — A 1530 Datassette recorder can be attached 
here to store programs and information. 

Cassette 



Pin 


Type 


A-1 


GND 


B-2 


4-5V 


C-3 


CASSETTE MOTOR 


D-4 


CASSETTE READ 


E-5 


CASSETTE WRITE 


F-6 


CASSETTE SENSE 



12 3 4 5 6 



A B C D E F 



7. Serial Port — A Commodore serial printer or disk drive can be 
attached directly to the Commodore 1 28 through this port. 



Serial I/O 




Pin 


Type 


1 

2 
3 
4 
5 
6 


SERIAL SRQIN 

GND 

SERIAL ATN IN/OUT 

SERIAL CLK IN/OUT 

SERIAL DATA IN/OUT 


RESET 




(view of port 
while facing the 
rear of the C1 28) 



APPENDIX 0— Connectors/Ports for Peripheral Equipment 



u 

u 
u 
u 
u 

u 

u 
u 
u 
u 
u 
u 
u 
u 
u 
u. 
u 
u 



' I 



n 



} 1 



8. Composite Video Connector— This DIN connector supplies 
direct audio and connposite video signals. These can be con- 
nected to the Connmodore nnonitor or used with separate 
components. This is the 40 column output connector. 



/ 1 



n 
n 

n 




(view of port while facing the rear of the C128) 



Pin 


Type 


Note 


1 


LUM/SYNC 


Luminance/SYNC output 


2 


GND 




3 


AUDIO OUT 




4 


VIDEO OUT 


Composite signal output 


5 


AUDIO IN 




6 


COLOR OUT 


Chroma signal output 


7 


NO 


No connection 


8 


NO 


No connection 



9. Channel Selector — Use this switch to select which TV channel 
(L = channels, H = channel 4) the computer's picture will be 
displayed on when using a television instead of a monitor. 

10. RF Connector— This connector supplies both picture and sound 
to your television set. (A television can display only a 40 column 
picture.) 
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1 1 . RGBI Connector— This 9-pin connector supplies direct audio and 
an RGBI (Red/Green/Blue/Intensity) signal. This is the 80-colunnn 
output. 




Pin 


Signal 


1 


Ground 


2 


Ground 


3 


Red 


4 


Green 


5 


Blue 


6 


Intensity 


7 


Monochrome 


8 


Horizontal Sync 


9 


Vertical Sync 



(rear view of port) 



12. User Port — Various interface devices can be attached here, 
including a Comnnodore nriodem. 

User I/O 



Pin 


Type 


Note 


1 


GND 




2 


+ 5V 


MAX. 100 mA 


3 


RESET 




4 


CNTl 




5 


SPl 




6 


CNT2 




7 
8 


SP2 
PC2 




9 


SER. ATN IN 




10 


9 VAC 


AAAX. 100 mA 


n 


9 VAC 


MAX. 100 mA 


12 


GND 





Pin 


Type 


Note 


A 


GND 




B 


FLAG2 




C 


PBO 




D 


PBl 




E 


PB2 




F 


PB3 




H 


PB4 




J 


PBS 




K 


PB6 




L 


PB7 




M 


PA2 




N 


GND 





1 2 3 4 5 6 7 8 9 10 11 12 



ABCDEFHJKLMN 

(rear view of port) 
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u 

u 
u 
u 
u 

u 

u 
u 
u 
u 
u 
u 
u 
u 
u 

u 
u 



n 



n 



n 

o 

n 
n 
n 



n 
n 
n 



APPENDIX D 
SCREEN DISPLAY 
CODES 

Screen Display 

Codes 

40 Columns 



The following chart lists all of the characters built into the Commo- 
dore screen character sets. It shows which numbers should be 
POKEd into the VIC chip (40 column) screen memory (location 1024 
to 2023) to get a desired character on the 40-column screen. 
(Remember, to set color memory, use locations 55296 to 56295.) 
Also shown is which character corresponds to a number PEEKed 
from the screen. 

Two character sets are available. Both are available simultaneously 
in 80-column mode, but only one is available at a time in 40-column 
mode. The sets are switched by holding down the SHIFT and fr 
(Commodore) keys simultaneously The entire screen of characters 
changes to the selected character set. 

From BASIC, PRINT CHR$(142) will switch to upper-case/graphics 
mode and PRINT CHR$(1 4) will switch to upper/lower-case mode. 

Any number on the chart may also be displayed in REVERSE. The 
reverse character code may be obtained by adding 1 28 to the values 
shown. 



sen 


SET 2 


POKE 


SET1 


SET 2 


POKE 


SET 1 SET 2 POKE 


@ 







N 


n 


14 


£ 


28 


A 


a 


1 








15 


] 


29 


B 


b 


2 


P 


P 


16 


T 


30 


C 


c 
d 

e 


3 
4 
5 


Q 

R 
S 


q 

r 

S 


17 

18 
19 


*- 


31 


D 


1 SPACE 


32 


E 


j 


33 


F 


f 


6 


T 


t 


20 


'• 


34 


G 


g 


7 


U 


u 


21 


# 


35 


H 


h 


8 


V 


V 


22 


$ 


36 


1 


i 


9 


w 


w 


23 


% 


37 


J 


i 


10 


X 


X 


24 


& 


38 


K 


k 


11 


Y 


y 


25 


' 


39 


L 


1 


12 


z 


z 


26 


( 


40 


M 


m 


13 


[ 




27 


) 


41 
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SET1 


SET 2 POKE 


SET1 


SET 2 


POKE 


SET1 


SET 2 POKE 


• 


42 


D 


G 


71 




100 


-f 


43 


m 


H 


72 


1 


101 


» 


44 


hj 


1 


73 


m 


102 


- 


45 


[\ 


J 


74 


1 


103 


. 


46 


cr 


K 


75 


u 


104 


/ 


47 


□ 


L 


76 


n 


105 





48 


N 


M 


77 


n 


106 


1 


49 


\7\ 


N 


78 


h 


107 


2 


50 


n 





79 


d 


108 


3 


51 


□ 


P 


80 


H 


109 


4 


52 


H 


Q 


81 


tiJ 


110 


5 


53 


L_ 


R 


82 


U 


111 


6 


54 


V 


S 


83 


Lc 


112 


7 


55 


D 


T 


84 


H 


113 


8 


56 


A 


U 


85 


tr 


114 


9 


57 


^ 


V 


86 


m 


115 


: 


58 


O 


w 


87 


u 


116 


; 


59 


1*1 


X 


88 


ij 


117 


< 


60 


LU 


Y 


89 


1 


118 


= 


61 


LiJ 


z 


90 


n 


119 


> 


62 


ffl 




91 


n 


120 


? 


63 


|] 




92 


u 


121 


— 


64 


m 




93 


u 


\/ 122 


♦ 


A 65 


vr 


fifl 


94 


y 


123 


m 


B 66 
C 67 
D 68 


a 


s 


95 
96 
97 


p 


124 


h 


1 SPACE ■ 


125 


M 


u 




126 


r 


E 69 


y 




98 


N 


127 


— 


F 70 


n 




99 







Codes from 128-255 are reversed images of codes 0-127. 
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u 

u 

LI 
U 
U 
U 
U 
U 

u 
u 
u 
u 
u 
u 
u 
u 

Li 
U 



n 



n 



n 



APPENDIX E 
ASCII AND CHR$ 
CODES 



ASCII and CHR$ 
Codes 



This appendix siiows you wiiat characters will appear if you PRINT 
CHR$(X), for all possible values of X. It also shows the values 
obtained by typing PRINT ASC ("x"), where x is any character that 
can be displayed. This is useful in evaluating the character received 
in a GET statennent, converting upper to lower case and printing 
character-based commands (like switch to upper/lower case) that 
could not be enclosed in quotes. 



PRINTS CHR$ 


PRINTS 


CHRS 


PRINTS 


CHRS 


PRINTS 


CHRS 







23 


. 


46 


E 


69 


1 




24 


/ 


47 


F 


70 


2 




25 





48 


G 


71 


3 




26 


1 


49 


H 


72 


4 




27 


2 


50 


1 


73 


g^ 


m 


28 


3 


51 


J 


74 


6 


m 


29 


4 


52 


K 


75 


7 


m 


30 


5 


53 


L 


76 


DISABLESBBGB^ 


m 


31 


6 


54 


M 


77 


ENABLES BB99 


ig 


32 


7 


55 


N 


78 


10 


! 


33 


8 


56 





79 


11 


" 


34 


9 


57 


P 


80 


12 


# 


35 




58 


Q 


81 


^^^Q 13 


$ 


36 


1 


59 


R 


82 


MA'JilliKliiM .. 
lltWiizMiMii^ *'* 


% 


37 


<z 


60 


S 


83 


15 


& 


38 


= 


61 


T 


84 


16 


. 


39 


3 


62 


U 


85 


B " 


( 


40 


? 


63 


V 


86 


n .a 


) 


41 


@ 


64 


w 


87 


B ^» 


* 


42 


A 


65 


X 


88 


B » 


+ 


43 


B 


66 


Y 


89 


21 


. 


44 


C 


67 


z 


90 


22 


- 


45 


D 


68 


I 


91 
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PRINTS 


CHR$ 


PRINTS 


CHRS 


PRINTS CHRS 


PRINTS 


CHRS 


£ 


92 


1^ 


115 


f4 138 


D 


161 


1 


93 


n 


116 


f6 139 




162 


T 


94 


u 


117 


f8 140 


n 


163 


.,- 


95 


X 


118 


BDOD^^i 




164 


— 


96 


u 


119 


Hi ^^2 


r 


165 


♦ 


97 


♦ 


120 


143 


a 


166 


1 


98 




121 


g^ 144 


u 


167 


h 


99 


♦ 


122 


Q 145 


u 


168 


— 


100 


ffl 


123 


im 146 


B 


169 


1 


101 


£J 


124 


B 147 


1 


170 


\- 


102 


m 


125 


H 14» 


Ih 


171 


u 


103 


rr 


126 


Brown 149 


1 1 


172 


1 


104 


n 


127 


Lt. Red 150 


L 

r 


173 


hk_ 


105 




128 


Dk. Gray 151 


174 


rr: 


106 


Orange 129 


Gray 152 


175 


Kl 


107 




130 


Lt. Green 153 


176 


U 


108 




131 


Lt. Blue 154 


ffl 


177 


N 


109 




132 


Lt. Gray 155 


T 


178 


/\ 


110 


f1 


133 


gg^ 156 


tu 


179 


n 


111 


f3 


134 


g 157 


u 


180 


n 


112 


f5 


135 


gg^ 158 


r 


181 


m 


113 


f7 


136 


JB^ 159 


n 


182 




114 


f2 


137 


BOB 160 


^ 


183 
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( t 



PRINTS 


CHR$ 


PRINTS 


CHR$ 


PRINTS 


CHR$ 


PRINTS 


CHRt 


u 


184 
185 


u 


186 
187 


"■ 
J 


188 
189 


n 


190 
191 



n 



CODES 


192-223 


SAME AS 


96-127 


CODES 


224-254 


SAIME AS 


160-190 


CODE 


255 


SAME AS 


126 



' 1 

n 
n 
n 
n 
n 



NOTE: The 80 column (RGBI) output has three colors which are different than the 40 
colunnn (connposite video) color output. This nneans that the character string codes 
that represent color codes for these three colors are used differently depending on 
which video output is used. The following character string codes represent these 
colors in each video output. 



CHR$ 

129 
149 
151 



40 Column (VIC Composite) 

Orange 

Brown 

Dark Gray 



80 Column (8563 RGBI) 

Dark Purple 
Dark Yellow 
Dark Cyan 



i \ 
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APPENDIX F 
SCREEN AND 
COLOR MEMORY 
MAPS 



Screen And Color 
Memory Maps— 
C128 Mode, 
40 Column 
And C64 Mode 



The following maps display the memory locations used in 40-column 
mode (C1 28 and C64) for identifying the characters on the screen as 
well as their color. Each map is separately controlled and consists of 
1 ,000 positions. 

The character displayed on the maps can be controlled directly with 
the POKE command. 



VIC CHIP (40 COLUMN) SCREEN MEMORY MAP 



COLUMN 

20 



1024- 

1064 

1104 

1144 

1184 

1224 

1264 

1304 

1344 

1384 

1424 

1464 

1504 

1544 

1584 

1624 

1664 

1704 

1744 

1784 

1824 

1864 

1904 

1944 

1984 



1083 



t 
2023 



The Screen Map is POKEd with a Screen Display Code value (see 
Appendix D). For example: 

POKE 1024, 13 

will display the letter M in the upper-left corner of the screen. 
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VIC CHIP (40 COLUMN) COLOR MEMORY MAP 



COLUMN 

20 



55335 



55296- 

55336 

55376 

55416 

55456 

55496 

55536 

55576 

55616 

55656 

55696 

55736 

55776 

55816 

55856 

55896 

55936 

55976 

56016 

56056 

56096 

56136 

56176 

56216 

56256 



: I I I I 1 1 I I "T'TT TjTn" 

i 



10 o 



56295 



The color RAM appears in this range in RAM BANKS and 1 . If the 
color nnap is POKEd with a color value; this changes the character 
color. For exannple: 

If the color map is POKEd with a color value; this changes the char- 
acter color. For example: 

POKE 55296,1 

will change the letter M inserted above from light green to white. 



Color Codes— 40 Columns 



Black 


8 Orange 


1 White 


9 Brown 


2 Red 


10 Light Red 


3 Cyan 


11 Dark Gray 


4 Purple 


12 Medium Gray 


5 Green 


13 Light Green 


6 Blue 


14 Light Blue 


7 Yellow 


15 Light Gray 



Border Control Memory 53280 
Background Control Memory 53281 
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APPENDIX G 
DERIVED 
TRIGONOMETRIC 
FUNCTIONS 



FUNCTION 


BASIC EQUIVALENT 


SECANT 


SEC(X)=l/COS(X) 


COSECANT 


CSC(X)=1/SIN{X) 


COTANGENT 


COT(X)=l/TAN(X) 


INVERSE SINE 


ARCSIN(X)=ATN(X/SQR(-X*X+ D) 


INVERSE COSINE 


ARCCOS(X)= - ATN(X/SQR 




(-X*X +1)) +77/2 


INVERSE SECANT 


ARCSEC(X)=ATN(X/SQR(X*X- D) 


INVERSE COSECANT 


ARCCSC(X)=ATN(X/SQR(X*X- D) 




+ (SGN(X)- 1*77/2 


INVERSE COTANGENT 


ARCOT(X)=ATN(X)+7r/2 


HYPERBOLIC SINE 


SINH(X)=(EXP(X)-EXP(-X))/2 


HYPERBOLIC COSINE 


COSH(X)=(EXP(X)+EXP(-X))/2 


HYPERBOLIC TANGENT 


TANH(X)=EXP(-X)/(EXP(x)+EXP 




{-X))*2+l 


HYPERBOLIC SECANT 


SECH(X)= 2/(EXP(X)+ EXP(- X)) 


HYPERBOLIC COSECANT 


CSCH(X)= 2/(EXP(X)- EXP(- X)) 


HYPERBOLIC COTANGENT 


COTH(X)=EXP(-X)/(EXP(X) 




-EXP(-X))*2H-1 


INVERSE HYPERBOLIC SINE 


ARCSINH(X)=LOG(X+SQR(X*X+l)) 


INVERSE HYPERBOLIC COSINE 


ARCCOSH(X)= LOG(X4-SQR(X*X- 1 )) 


INVERSE HYPERBOLIC TANGENT 


ARCTANH(X)=LOG((l+X)/(l-X))/2 


INVERSE HYPERBOLIC SECANT 


ARCSECH(X)=LOG((SQR 




(-X*X+1)+1/X) 


INVERSE HYPERBOLIC COSECANT 


ARCCSCH(X)=LOG((SGN(X)*SQR 




(X*X+l/x) 


INVERSE HYPERBOLIC COTANGENT 


ARCCOTH(X)= LOG((X+ 1 )/(x- 1 ))/2 



1 I 
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APPENDIX H 
MEMORY MAP 



System Memory 
Map 



The Commodore 128 memory map is shown below. 



COMMODORE 128 MODE 
MEMORY MAP 



COMMODORE 128 MODE 
MEMORY MAP 



FFFF 
FFFA 
FFDO 



FF05 



FFOO 



C128 
RAM 



4000 



NMI RST IRQ 
CP/M RAM Code 
KrnI RAM Code 



MMU 

Configuration Register 



BASIC TEXT AREA 
(Basic text begins 
at $1C00 if bit-map 
unallocated) 



FFFF 
FF4D 

FF05 
FFOO 

FC80 

FA80 

EOOO 
DOOO 

COOO 
BOOO 

8000 
4000 



C128 
ROM 



////////// 
////////// 
///////// 
///////// 



////////// 
////////// 
////////// 
////////// 



- Kernal Jump Table & - 
Hardware Vectors 



- Kernal Interrupt 
Dispatch Code 



- MMU Configuration 
Registers 



- ROM Reserved for 
Foreign Lang. Versions 



-Editor Tables 



- Kernal ROM Code 



I/O Space 



- Editor ROM Code- - 
-Monitor ROM Code - 



Basic ROM Code _ 



*\HIGH 
/ROM 



\MID 
/ROM 



vLOW 
^ROM 
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4000 



2000 

1C00 
1B00 
1A00 



1400 
1300 

1200 

1108 

1100 

1000 
OFOO 
OEOO 

ODOO 

OCOO 
OBCO 
OBOO 

OAOO 
0900 
0800 



0400 
0380 
033C 
02FC 
02A2 

0200 

0149 

0110 

0100 

0090 

0002 
0000 



C128 
RAM 



VIC BIT-MAP 
Screen 



VIC BIT-MAP 
Color (Vm #2) 



Reserved for 
Applications 



Reserved for 
Applications 



Reserved for 
Applications 



Basic 
Absolute 
Variables 



Basic 
DOS/VSP 
Variables 



CP/M Reset 
Code 



Function 

Key 

Buffer 



Sprite 

Definition 

Area 



RS-232 
Output 
Buffer 



RS-232 
Input 
Buffer 



|Djsk Boot^age)_ 
Cassette Buffer 



Monitor & Kernal 
Absolute 
Variables 



Basic 

Run-Time 

Stack 



VIC 

Text 
Screen 
(VM#1) 



Basic RAM_Code_ 
Kernal Tables 



Indirects 



Kernal RAM Code 



Basic & Monitor 
Input Buffer 



System Stack 



Basic DOS_Using_ 
F BUFFER 



_KernaJIZ.P. 
Basic Z.R 



4000 



C128 
ROM 



COMMODORE 64 MODE 
MEMORY MAP 



C64 
Cartridges 

FFFF , , FFFF 



EOOO 



DOOO 



COOO 



BOOO 
AOOO 



8000 



GAME CARD 



I/O. Char ROM 
or RAM 



RAM {4K) 



Application ROM 
Card-HI 



Application ROM 
Card-LO 



EOOO 



DOOO 



COOO 



C64 



KERNAL 

and 
EDITOR 



I/O and Chars 
ROM or RAM 



RAM (4K) 



BASIC ROM 
or RAM (8K) 



RAM 



COMMODORE 64 MODE 
MEMORY MAP 



4000 



C64 
Cartridaes 



C64 



BASIC PROGRAM SPACE 



VIC {40 Column) TEXT 
SCREEN 



SYSTEM STACK 
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APPENDIX I 
CONTROL AND 
ESCAPE CODES 

Control Codes 



n 



n 

n 
n 
n 



The following are the control codes used by the Comnnodore 1 28. 
The first colunnn, Print Codes, are used in PRINT statennents. The 
second column is the key codes. Key codes are the sequence of 
keys pressed to perform specific controls. Hold down the control key 
(or the key specified on the left in the key code column) and strike 
the key specified to the right in the key code column. 



Print Codes 


J 


<ey Codes 
Key 




Effective 

in 

Mode: 


(CHR$) 




Sequence 


Function ( 


364 


C128 


CHR$(2) 


CTRLB 




Underline (80) 




* 


CHR$(5) 


CTRL 2 or CTRL E 


Set character color to 












white 


* 


• 


CHR$(7) 


CTRLG 




Produce bell tone 




* 


CHR$(8) 


CTRLH 




Disable character set 
change 


Vf 




CHR$(9) 


CTRLI 




Enable character set 

change 

Move cursor to next 

set tab position 


* 


* 


CHR$(10) 


CTRL J 




Line feed 




* 


CHR$(11) 


CTRLK 




Enable character set 
change 




* 


CHR$(12) 


CTRLL 




Disable character 
mode change 




• 


CHR$(13) 


CTRLM 




Send a carriage return 
and line feed to the 
computer and enter a 












line of BASIC 


* 


• 


CHR$(14) 


CTRLN 




Set character set to 












upper/lowercase 


* 


* 


CHR$(15) 


CTRLO 




Turn flash on (80) 




* 


CHR$(17) 


CRSR DOWN/CTRL 


Move the cursor down 












one row 


* 


* 


CHR$(18) 


CTRL 9 or CTRL R 


Cause characters to 












be printed in reverse 












field 


• 


* 


CHR$(19) 


HOME 




Move the cursor to the 
home position (top left) 
of the display (the cur- 












rent window) 


* 


• 



NOTE: (40) ... 40 column screen only 
(80) ... 80 column screen only 



\ ) 
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Effective 

in 






Key 




in 
Mode: 


CHR$ 


Sequence 


Function 


C64 


C128 


CHR$(20) 


DEL or 


CTRLT 


Delete last character 
typed and move all 
characters to the right 
of the deleted charac- 
ter one space to the 












left 


* 


* 


CHR$(24) 


CTRL X, CTRL TAB 
orfrTAB 


Tab set/clear 






^ CHR$(27) 


ESC or 


CTRL[ 


Send an ESC 
character 




* 


CHR$(28) 


CTRL 3 


or CTRL £ 


Set character color to 












red (40) and (80) 


* 


* 


CHR$(29) 


CRSRorCTRL] 


Move cursor one 












column to the right 


* 


* 


CHR$(30) 


CTRL 6 


or CTRL f 


Set character color to 












green (40) and (80) 


* 


• 


CHR$(31) 


CTRL? 


or CTRL = 


Set character color to 
blue (40) and (80) 






CHR$(34) 






Print a double quote on 
screen and place edi- 












tor in quote mode 


• 


• 


CHR$(129) 


Ol 




Set character color to 
orange (40); dark pur- 












ple (80) 


* 


* 


CHR$(130) 






Underline off (80) 




• 


CHR$(131) 






Run a program. This 
CHR$ code does not 
worl< in PRINT CHR$ 
(131), but works from 












keyboard buffer 


• 


• 


CHR$(133) 


F1 




Reserved CHR$ code 












for F1 key 


* 


* 


CHR$(134) 


F3 




Reserved CHR$ code 












for F3 key 


• 


* 


CHR$(135) 


F5 




Reserved CHR$ code 












for F5 key 


* 


* 


CHR$(136) 


F7 




Reserved CHR$ code 












for F7 key 


* 


• 


CHR$(137) 


F2 




Reserved CHR$ code 












for F2 key 


* 


* 


CHR$(138) 


F4 




Reserved CHR$ code 












for F4 key 


• 


• 


CHR$(139) 


F6 




Reserved CHR$ code 












for F6 key 


* 


* 


CHR$(140) 


F8 




Reserved CHR$ code 












for F8 key 


* 


* 
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CHR$ 



Key 
Sequence 



Function 



Effective 

in 

Mode: 

C64 C128 
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CHR$(141) SHIFT RETURN. CTRL 
ENTER, fr ENTER or O 
RETURN 

CHR$(142) 

CHR$(143) 
CHR$(144) CTRL1 

CHR$(145) CRSRUP 

CHR$(146) CTRLO 

CHR$(147) CLEAR HOME 



CHR$(148) INST 

CHR${149) C-2 

CHR$(150) C-3 

CHR$(151) C-4 

CHR$(152) frS 

CHR$(153) C-6 

CHR$(154) Cf7 

CHR$(155) 08 

CHR$(156) CTRL 5 

CHR$(157) CRSRLEFT 

CHR$(158) CTRL 8 

CHR$(159) or CTRL 4 

APPENDIX I— Control and Escape Codes 



Send a carriage return 
and line feed without 
entering a BASIC line 
Set the character set 
to uppercase/graphic 
Turn flash off (80) 

Set character color to 
black (40) and (80) 
Move cursor or print- 
ing position up one row 
Ternninate reverse field 
display 

Clear the window 
screen and nnove the 
cursor to the top left 
position 

Move character f ronn 
cursor position end of 
line right one colunnn 
Set character color to 
brown (40); dark yellow 
(80) 

Set character color to 
light red (40) and (80) 
Set character color to 
dark grey (40); dark 
cyan (80) 

Set character color to 
nnediunn grey (40) and 
(80) 

Set character color to 
light green (40) and 
(80) 

Set character color to 
light blue (40) and (80) 
Set character color to 
light grey (40) and (80) 
Set character color to 
purple (40) and (80) 
Move cursor left by 
one column 
Set character color to 
yellow (40) and (80) 
Set character color to 
cyan (40); light cyan 
(80) 



Escape Codes 



Following are key sequences for the ESCape functions available on 
the Commodore 128. ESCape sequences are entered by pressing 
and releasing the "ESC" key followed by pressing the key listed 
below. 

ESCAPE FUNCTION 

Cancel quote mode 

Erase to end of current line 
Erase to start of current line 
Clear to end of screen 

Move to start of current line 
Move to end of current line 

Enable auto-insert mode 
Disable auto-insert mode 

Delete current line 
Insert line 

Set default tab stop (8 spaces) 
Clear all tab stops 

Enable scrolling 
Disable scrolling 

Scroll up 
Scroll down 

Enable bell (by control-G) 
Disable bell 

Set cursor to non-flashing mode 
Set cursor to flashing mode 

Set bottom of screen window at cursor position 
Set top of screen window at cursor position 

Swap 40/80 column display output device ESC X 

The following ESCape sequences are valid on an 80-column screen 
only (See Section 8 for information on using an 80-column screen.) 

Change to underlined cursor ESC U 

Change to block cursor ESC S 

Set screen to reverse video ESC R 

Return screen to normal (non reverse video) state ESC N 



ESCAPE KEY 


ESCC 


ESCQ 
ESCP 
ESC® 


ESC J 
ESCK 


ESC A 
ESCQ 


ESCD 
ESCI 


ESCY 
ESCZ 


ESCL 
ESCM 


ESCV 
ESCW 


ESCG 
ESCH 


ESCE 
ESCF 


ESCB 
ESCT 
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APPENDIX J 
MACHINE 
LANGUAGE 
MONITOR 

Introduction 



' 






KEYWORD 




ASSEMBLE 


n 


COMPARE 


n 


DISASSEMBLE 

FILL 

GO 



HUNT 

JUMP 
LOAD 
MEMORY 

REGISTERS 
SAVE 

TRANSFER 



VERIFY 
EXIT 
(period) 
(greater than) 
(semicolon) 
(at sign) 



Commodore 128 has a built-in machine language monitor program 
which lets the user write and examine machine language programs 
easily. Commodore 128 MONITOR includes a machine language 
monitor, a mini-assembler and a disassembler. The built-in monitor 
works only in C128 mode; either 40 column or 80 column. 

Machine language programs written using Commodore 1 28 MONI- 
TOR can run by themselves or be used as very fast subroutines for 
BASIC programs since the Commodore 1 28 MONITOR has the abil- 
ity to coexist peacefully with BASIC. 

Care must be taken to position the assembly language programs in 
memory so the BASIC program does not overwrite them. 

To enter the monitor from BASIC, type: 

monitor: 



Summary of Commodore 1 28 Monitor Commands 

FUNCTION FORMAT 

Assembles a line of 8502 code A <start_address> (opcode) [operand] 



Compares two sections of memory and reports C 
differences 

Disassembles a line or lines of 8502 code D 

Fills a range of memory with the specified byte F 
Starts execution at the specified address G 

H 



<starLaddress> <end_address> (new.startad- 

dress) 

[<start_address> <encLaddress]] 

<starLaddress> <end_address> <byte> 

[address] 

<start_address> <end_address> <byte1> 

[<byte_n>...] 



Hunts through memory within a specified range 

for all occurrences of a set of bytes 

Jumps to the subroutine 

Loads a file from tape or disk 

Displays the hexadecimal values of memory 

locations 

Displays the 8502 registers 

Saves to tape or disk 

Transfers code from one section of memory to 
another 

Compares memory with tape or disk 
Exits Commodore 128 MONITOR 
Assembles a line of 8502 code 
Modifies memory 
Modifies 8502 register displays 
Displays disk status, sends disk command, dis- 
plays directory 
disk status 
disk command 
disk catalog 



H <starLaddress> <end_address> '<ascii_string> 



J 
L 
M 

R 
S 



[address] 

"(filename)" [,(device_#) [,(load_address)]] 

[(start_address) [end_address]] 



"(filename)", (device_#),(starLaddress) 
(lasLaddress + 1) 

(start_address) (end_address) ( new_star Lad- 
dress) 

"(filename)" [,(device_#) [,(load_address>]] 



@[device_#] 

@[device_#][,(commancLstring)] 

@[device_#],$[[(drive)][:(file_spec)]] 



NOTES: ( ) enclose required parameters. 
[ ] enclose optional parameters. 



NOTE: See important 5-digit Address note on the next page. 
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NOTE: 5-Digit Addresses 

The Commodore 128 displays 5-digit hexadecimal addresses within 
the machine language monitor. Normally, a hexadecimal number is 
only four digits, representing the allowable address range. The extra 
left-most (high order) digit specifies the BANK configuration (at the 
time the given command is executed) according to the following 
memory configuration table: 

O-RAM only 8~EXT ROM, RAM 0, I/O 

1-RAM 1 only 9-EXT ROM, RAM 1, I/O 

2— RAM 2 only A-EXT ROM, RAM 2, I/O 

3-RAM 3 only B-EXT ROM, RAM 3, I/O 

4-INT ROM, RAM 0, I/O C-KERNAL + INT (lo), RAM 0, I/O 

5-INT ROM, RAM 1, I/O D-KERNAL + EXT (lo), RAM 1, I/O 

6-INT ROM, RAM 2, I/O E-KERNAL + BASIC, RAM 0, CHARROM 

7-INT ROM, RAM 3, I/O F-KERNAL + BASIC, RAM 0, I/O 

Summary of Monitor Field Descriptors 

The following designators precede monitor data fields (e.g., memory 
dumps). When encountered as a command, these designators 
instruct the monitor to alter memory or register contents using the 
given data. 

. <period> precedes lines of disassembled code. 
> <right_angle> precedes lines of a memory dump. 
; < semicolon) precedes line of a register dump. 

The following designators precede number fields (e.g., address) and 
specify the radix (number base) of the value. Entered as commands, 
these designators instruct the monitor simply to display the given 
value in each of the four radices. 

<null> (default) precedes hexadecimal values. 
$ <dollar> precedes hexadecimal (base-16) values. 
+ <plus> precedes decimal (base-10) values. 
& (ampersand) precedes octal (base-8) values. 
% (percent) precedes binary (base-2) values. 

«^ 

The following characters are used by the monitor as field delimiters 
or line terminators (unless encountered within an ASCII string). 

(space) delimiter — separates two fields. 
, (comma) delimiter — separates two fields. 
: (colon) terminator — logical end of line. 
? (question) terminator — logical end of line. 
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Commodore 1 28 
Monitor 
Command 
Descriptions 



Number field (e.g. addresses, device numbers, and data bytes) may 
be specified as a based number. This affects tine operand field of the 
ASSEMBLE command. Also note the addition of the directory syntax 
to the disk command. 

As a further aid to programmers, the Kernal error message facility 
has been automatically enabled while in the Monitor. This means the 
Kernal will display 'I/O ERROR #' and the error code, should there be 
any failed I/O attempt from the MONITOR. The message facility is 
turned off when exiting the MONITOR. 

COMMAND: A 

PURPOSE: Enter a line of assembly code. 

SYNTAX: A <address> <opcode mnemonic) (operand) 



(address) 



(opcode 
mnemonic) 



(operand) 



A number indicating the location 
in memory to place the opcode. 
(See 5-digit address note on pre- 
vious page.) 

A standard MOS technology 

assembly language mnemonic, 

e.g., LDA, STX, ROR. 

The operand, when required, can 

be any of the legal addressing 

modes. 



A RETURN is used to indicate the end of the assembly line. If there 
are any errors on the line, a question mark is displayed to indicate an 
error, and the cursor moves to the next line. The screen editor can 
be used to correct the error(s) on that line. 

EXAMPLE 

.A01200LDX#$00 

.A01202 

NOTE: A period (.) is equal to the ASSEMBLE command. 

EXAMPLE: 
.02000 LDA #$23 
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COMMAND: 

PURPOSE: 

SYNTAX: 



Compare two areas of memory. 

C <address 1 > <address 2> (address 3> 

<address 1 > A number indicating the start 

address of the area of memory to 
compare against. 

(address 2> A number indicating the end 

address of the area of memory to 
compare against. 

(address 3> A number indicating the start 

address of the other area of mem- 
ory to compare with. Addresses 
that do not agree are printed on 
the screen. 



Disassemble machine code into assembly language 
mnemonics and operands. 
D [(address)] [(address 2>] 

(address) A number setting the address to 
start the disassembly 

(address 2) An optional ending address of 
code to be disassembled. 



The format of the disassembly differs slightly from the input format of 
an assembly The difference is that the first character of a disassem- 
bly is a period rather than an A (for readability), and the hexadecimal 
of the code is listed as well. 

A disassembly listing can be modified using the screen editor. Make 
any changes to the mnemonic or operand on the screen, then hit the 
carriage return. This enters the line and calls the assembler for fur- 
ther modifications. 

A disassembly can be paged. Typing a D (RETURN) causes the next 
page of disassembly to be displayed. 



COMMAND: 
PURPOSE: 

SYNTAX: 



EXAMPLE: 




D 3000 3003 




.03000 A900 


LDA#$00 


.03002 FF 


??? 


.03003 DO 2B 


BNE $3030 



u 
u 
u 
u. 
u 
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COMMAND: F 

PURPOSE: Fill a range of locations with a specified byte. 

SYNTAX: F <address 1 > (address 2> <byte> 

(address 1 > The first location to fill with the 
<byte>. 

(address 2> The last location to fill with the 
(byte). 

( byte value) A 1 - or 2-digit hexadecimal num- 
ber to be written. 

This command is useful for initializing data structures or any other 
RAM area. 

EXAMPLE: 

F 0400 0518 EA 

Fill memory locations from $0400 to $051 8 with $EA (a 
NOP instruction). 

COMMAND: G 

PURPOSE: Begin execution of a program at a specified address. 

SYNTAX: G [(address)] 

(address) An address where execution is to 
start. When address is left out, 
execution begins at the current 
PC. (The current PC can be 
viewed using the R command.) 

The GO command restores all registers (displayable by using the R 
command) and begins execution at the specified starting address. 
Caution is recommended in using the GO command. To return to 
Commodore 128 MONITOR mode after executing a machine lan- 
guage program, use the BRK instruction at the end of the program. 

EXAMPLE: 

G140C 

Execution begins at location $140C. 
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COMMAND: H 

PURPOSE: Hunt through memory within a specified range for all 

occurrences of a set of bytes. 
SYNTAX: H (address 1 > (address 2> <data> 



<address1> 
< address 2 > 
<data> 



Beginning address of hunt 

procedure. 

Ending address of hunt 

procedure. 

Data set to search for data may 

be hexadecimal or an ASCII 

string. 



EXAMPLE: 

HA000A101 A9FF4C 

Search for data $A9, $FF, $4C, 
fromAOOOtoAIOL 

H 2000 9800 'CASH' 

Search for the alpha string "CASH". 

COMMAND: J 

PURPOSE: Jump to a machine language subroutine 

SYNTAX: J < address) 

The JUMP command directs program control to the machine lan- 
guage subroutine located at the specified address. The JUMP com- 
mand does not save the return address as does the 8502 instruction 
JSR (Jump to subroutine). The JMP 8502 instruction is comparable to 
the J monitor instruction. In other words, the JUMP command is a 
one-way instruction, where the application gains control of the com- 
puter. Only after it stops does the machine language monitor regain 
control. 

EXAMPLE: 

J 2000 
Jump to the subroutine starting at $2000. 

COMMAND: L 

PURPOSE: Load a file from cassette or disk. 

SYNTAX: L <"file name">[,<device> [,alt load address]] 

< "file name" > Any legal Commodore 1 28 file 

name, 
(device) A number indicating the device to 

load from. 1 is cassette. 8 is disk 

(or 9, A, etc.). 



u 
u 
u 
u 



u 
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[alt load address] Option to load a file to a speci- 
fied address. 

The LOAD command causes a file to be loaded into memory. The 
starting address is contained in the first two bytes of the disk file (a 
program file). In other words, the LOAD command always loads a file 
into the same place it was saved from. This is very important in 
machine language work, since few programs are completely relocat- 
able. The file is loaded into memory until the end of file (EOF) is 
found. 

EXAMPLE: 

L "PR0GRAM",8 Loads the file named PROGRAM from the 
disk. 
COMMAND: M 
PURPOSE: To display memory as a hexadecimal and ASCII dump 

within the specified address range. 
SYNTAX: M [< address 1 >] [<address>] 

{address 1 > First address of memory dump. 
Optional. If omitted, one page is 
displayed. The first byte is the 
bank number to be displayed, the 
next four bytes are the first 
address to be displayed. 

{address 2> Last address of memory dump. 
Optional. If omitted, one page is 
displayed. The first byte is the 
bank number to be displayed, the 
next four bytes are the ending 
address to be displayed. 
Memory is displayed in the following format: 

>1A04841 E7 00AAAA00 98 56 45:A!.*..VE 
Memory content may be edited using the screen editor. Move the 
cursor to the data to be modified, type the desired correction and hit 
< RETURN). If there is a bad RAM location or an attempt to modify 
ROM has occurred, an error flag (?) is displayed. An ASCII dump of 
the data is displayed in REVERSE (to contrast with other data dis- 
played on the screen) to the right of the hex data. When a character 
is not printable, it is displayed as a reverse period (o). As with the dis- 
assembly command, paging down is accomplished by typing M and 
{RETURN). 

EXAMPLE: 
M21C00 21C10 

)21C00 41 E7 00 AA AA 00 98 56-45 :A!.*..VE 



) \ 



i \ 
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R 

PC SR AC XR YR SP 
; 01002 01 02 03 04 F6 

NOTE: ; (semicolon) can be used to modify register displays in 
the same fashion as > can be used to modify memory registers. 

COMMAND; S 

PURPOSE: Save the contents of memory onto tape or disk. 
SYNTAX: S <"filename">,<device>,<address 1>, 
< address 2 > 



1 i 



>21 COS 42 43 02 AZ AD 1 1 94 57 44 :BC. *..WD 
>21C10 45E7 00DFFE07 06 46 47:E!.*..EF 

Note: The above display is produced by the 40-column editor. 

COMMAND: R 

PURPOSE: Show important 8502 registers. The program status 

register, the program counter, the accumulator, the 1 j 

X and Y index registers and the stack pointer are 

displayed. 

SYNTAX: R 

EXAMPLE: 



L' 
U 
U 

U 

u 
u 



< "file name" > Any legal Commodore 1 28 file 
name. To save the data the file 
name must be enclosed in double 
quotes. Single quotes cannot be 
used. 

<device> A number indicating on which 

device the file is to be placed. 
Cassette is 01 ; disk is 08, 09, etc. Jl 

(address 1 > Starting address of memory to be ' — 

saved. 

<address 2> Ending address of memory to be j 1 

saved + 1 . All data up to, but not — ^ 

including the byte of data at this 
address, is saved. IJ 

The file created by this command is a program file. The first two 

bytes contain the starting address (address 1 > of the data. The file . 

may be recalled, using the L command. LJ 

u 
u 
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EXAMPLE: 

S"GAME",8,0400,0BFF 
Saves memory from $0400 to $OBFF onto disk. 

COMMAND: T 

PURPOSE: Transfer segments of memory from one memory area 

to another. 
SYNTAX: T <address 1 > (address 2> (address 3> 

(address 1 > Starting address of data to be 

moved, 
(address 2> Ending address of data to be 

moved, 
(address 3> Starting address of new location 

where data will be moved. 

Data can be moved from low memory to high memory and vice 
versa. Additional memory segments of any length can be moved 
forward or backward. An automatic "compare" is performed as 
each byte is transferred, and any differences are listed by address. 

EXAMPLE: 

T 1400 1600 1401 

Shifts data from $1 400 up to and including $1 600 one byte 
higher in memory 

COMMAND: V 

PURPOSE: Verify a file on cassette or disk with the memory con- 
tents. 
SYNTAX: V ("file name">[,(device>] [,alt start address] 

( "file name" > Any legal Commodore 1 28 file 

name, 
(device) A number indicating which device 

the file is on; cassette is 01 , disk is 

08, 09, etc. 
[alt start Option to start verification 

address] at this address. 

The verify command compares a file to memory contents. The 
Commodore 128 responds with VERIFYING. If an error is found the 
word ERROR is added; if the file is successfully verified the cursor 
reappears. 

EXAMPLE: 

V "WORKLOAD", 08 
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COMMAND: 

PURPOSE: 

SYNTAX: 

COMMAND: 
PURPOSE: 

SYNTAX: 



Exit to BASIC. 
X 

> (greater than) 

Can be used to set one to eight memory locations 
at a time. 

> <address> <data byte) 1 <data byte 2 . . . 8> 

<address> First memory address to set. 

<data byte 1 > Data to be put at address. 

<databyte2...8> 

Data to be placed in the suc- 
cessive memory locations 
following the first address 
(optional) with a space pre- 
ceding each data byte. 

@ (at sign) 

Can be used to display the disk status. 

@ [<unit#>], (disk cmd string) 

<unit #) Device unit number 

(optional). 
<disk cmd string) String command to disk. 



NOTE: @ alone gives the status of the disk drive. 

EXAMPLES: 

checks disk status 

00. OK, 00, 00 

initializes drive 8 

Checks the directory on Unit 8 

@,$0:F* List all files on Unit 8, drive beginning with the 
letter "F". 



COMMAND: 

PURPOSE: 

SYNTAX: 



@ 

@.l 
@,$ 
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ABBREVIATIONS 
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Note: The abbreviations below operate in uppercase/graphics mode. 
Press the letter key(s) indicated, then hold down the SHIFT key 
and press the letter key following the word SHIFT 

KEYWORD ABBREVIATrON 

ABS A SHIFTS 

APPEND. A SHIFT P 

ASC A SHIFTS 

ATN ASHIFTT 

AUTO A SHIFT U 

BACKUP BA SHIFTC 

BANK B SHIFT A 

BEGIN B SHIFT E 

BEND BE SHIFT N 

BLOAD B SHIFT L 

BOOT BSHIFTO 

BOX none 

BSAVE B SHIFTS 

BUMP B SHIFT U 

CATALOG C SHIFTA 

CHAR CH SHIFTA 

CHR$ C SHIFT H 

CIRCLE CSHIFTI 

CLOSE CLSHIFTO 

CLR C SHIFT L 

CMD C SHIFT M 

COLLECT COLL SHIFTE 

COLLISION COL SHIFT L 

COLOR COL SHIFTO 

CONCAT C SHIFTO 

CONT none 

COPY CO SHIFT P 

COS none 

DATA D SHIFTA 

DEC none 

DCLEAR DCL SHIFTE 

DOLOSE D SHIFTC 

DEFFN none 

DELETE DESHIFTL 

DIM DSHIFTI 

DIRECTORY DISHIFTR 

DLOAD D SHIFT L 

DO none 

DOPEN D SHIFTO 



n 
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KEYWORD ABBREVIATION i ^ 

DRAW D SHIFT R 

DSAVE D SHIFTS 

DVERIFY DSHIFTV 

EL none 

END none 

ENVELOPE E SHIFT N 

ER none 

ERRS ESHIFTR 

EXIT EXSHIFTI ; ; 

EXP ESHIFTX ^ 

FAST none 

FETCH FSHIFTE 

FILTER FSHIFTI 

FOR FSHIFTO 

FRE F SHIFT R 

FNXX none 

GET G SHIFT E 

GETKEY GETK SHIFT E 

GET # none 

GOSUB GO SHIFT S 

G064 none 

GOTO GSHIFTO 

GRAPHIC GSHIFTR 

GSHAPE G SHIFTS 

HEADER HESHIFTA 

HELP HEX$ H SHIFT E 

IF. ..GOTO none 

IF. ..THEN... ELSE none 

INPUT none 

INPUT# I SHIFT N 

INSTR IN SHIFTS 

INT none 

JOY JSHIFTO I I 

KEY K SHIFT E Li 

LEFTS LE SHIFT F 

LEN none . 

LET L SHIFT E U 

LIST LSHIFTI 

LOAD LSHIFTO 

LOCATE LO SHIFTC U 

LOG none 

LOOP LOSHIFTO ^ 

u 
u 



u 
u 
u 
u 

LI 
U 
U 
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KEYWORD ABBREVIATION 

MID$ MSHIFTI 

MONITOR MO SHIFT N 

MOVSPR MSHIFTO 

NEW none 

NEXT N SHIFT E 

ON . . . GOSUB ON ... GO SHIFT S 

ON . . . GOTO ON ... G SHIFTO 

OPEN O SHIFT P 

PAINT P SHIFT A 

PEEK PE SHIFT E 

PEN P SHIFT E 

PI none 

PLAY P SHIFT L 

POKE PO SHIFT K 

POS none 

POT P SHIFTO 

PRINT ? 

PRINT# PSHIFTR 

PRINT USING 7USSHIFTI 

PUDEF P SHIFT U 

RCLR R SHIFTO 

ROOT R SHIFT D 

READ RE SHIFT A 

RECORD R SHIFT E 

REM none 

RENAME RE SHIFT N 

RENUMBER REN SHIFT U 

RESTORE RE SHIFTS 

RESUME RES SHIFT U 

RETURN RESHIFTT 

RGR RSHIFTG 

RIGHTS RSHIFTI 

RND R SHIFT N 

RREG R SHIFT R 

RSPCOLOR RSP SHIFTO 

RSPPOS R SHIFTS 

RSPR none 

RSPRITE RSP SHIFT R 

RUN R SHIFT U 

RWINDOW R SHIFT W 
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KEYWORD ABBREVIATION 

SAVE SSHIFTA 

SCALE SCSHIFTA 

SCNCLR SSHIFTC , > 

SCRATCH SC SHIFT R U 

SGN SSHIFTG 

SIN SSHIFTI 

SLEEP S SHIFT L 

SLOW none 

SOUND S SHIFT O ^ 

SPC( none U-* 

SPRCOLOR SPR SHIFTC 

SPRDEF SPR SHIFT D , 

SPRITE S SHIFT P U 

SPRSAV SPR SHIFT S 

SQR SSHIFTQ , , 

SSHAPE S SHIFTS U 

STASH SSHIFTT 

STatus none . 

STEP ST SHIFT E U 

STOP STSHIFTO 

STR$ ST SHIFT R . , 

SWAP S SHIFT W LJ 

SYS none 

TAB( T SHIFT A 

TAN none LJ 

TEMPO T SHIFT E 

Tl none 

Tl$ none LJ 

TO none 

TRAP T SHIFT R . 

TROFF TRO SHIFT F LJ 

TRON TRSHIFTO 

UNTIL U SHIFT N . ^ 

USR U SHIFTS [_] 

VAL none 

VERIFY VSHIFTE 

VOL VSHIFTO LJ 

WAIT WSHIFTA 

WHILE W SHIFT H 

WIDTH WI SHIFT D \i 

WINDOW WSHIFTI 

XOR XSHIFTO 

u 
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This appendix lists tine commands used for disk operation in C128 
and C64 modes on tlie Commodore 128. For detailed information on 
any of tlnese commands, see Chapter V, BASIC 7.0 Encyclopedia. 
Your disk drive manual also has information on disk commands. 

The new BASIC 7.0 commands can be used only in C128 mode. All 
BASIC 2.0 commands can be used in both C128 and C64 modes. 



Command 


Use 


Basic 2.0 


Basic 7.0 


APPEND 


Append data to file 




»^ 


BLOAD 


Load a binary file starting at 
the specified memory 
location 




\^ 


BOOT 


Load and execute a bootable 
program 




t^ 


BSAVE 


Save a binary file from the 
specified memory location 




i/' 


CATALOG 


Display directory contents of 
disk on screen* 




#^ 


CLOSE 


Close logical disk file 


1^ 




CMD 


Redirect screen output to a 
peripheral device 


*> 




COLLECT 


Free inaccessible disk 
space* 




1^ 


CONCAT 


Concatenate two data files* 




i^ 


COPY 


Copy files between devices* 




^ 


DCLEAR 


Clear all open channels on 
disk drives 




i/' 


DOLOSE 


Close logical disk file 




^ 


DIRECTORY 


Display directory of contents 
of disk on screen* 




»^ 


DLOAD 


Load a BASIC program from 
disk 




*^ 


DOPEN 


Open a disk file for a read 
and/or write operation 




1^ 


DSAVE 


Save a BASIC program to 
disk 




t^ 


DVERIFY 


Verify program in memory 
against program on disk 




^ 


GET* 


Receive input from open disk 
file 


*^ 




HEADER 


Format a disk* 




^ 


LOAD 


Load a file from disk 


i^ 




OPEN 


Open a file for input or output 


i^ 




PRINT* 


Output a data to file 


1^ 





* Although there is no single equivalent command for this function in BASIC 2.0, there is an 
equivalent multi-command instruction. See your disk drive manual for these BASIC 2.0 
conventions. 
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Command 


Use 


Basic 2.0 


Basic 7.0 


RECORD 


Position relative file pointers* 




i^ 


RENAME 


Change name of a file on 
disk* 




#^ 


RUN filename 


Execute BASIC program from 
disk 




f^ 


SAVE 


Store program in memory to 
disk 


i^ 




VERIFY 


Verify program in memory 
against program on disk 


1^ 





*Although there is no single equivalent command in BASIC 2.0, there is an equivalent multi- 
command instruction. See your disk drive manual for these BASIC 2.0 conventions. 
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This glossary provides brief definitions of frequently used computing 
terms. 

Acoustic Coupler or Acoustic IVIodem: A device that converts 
digital signals to audible tones for transmission over telephone 
lines. Speed is limited to about 1 ,200 baud, or bits per second 
(bps). Compare direct-connect modem. 

Address: The label or number identifying the register or memory 
location where a unit of information is stored. 

Alphanumeric: Letters, numbers and special symbols found on the 
keyboard, excluding graphic characters. 

ALU: Arithmetic Logic Unit. The part of a Central Processing Unit 
(CPU) where binary data is acted upon. 

Animation: The use of computer instructions to simulate motion of 
an object on the screen through gradual, progressive 
movements. 

Array: A data-storage structure in which a series of related con- 
stants or variables are stored in consecutive memory locations. 
Each constant or variable contained in an array is referred to as 
an element. An element is accessed using a subscript. See 
Subscript. 

ASCII: Acronym for American Standard Code for Information Inter- 
change. A seven-bit code used to represent alphanumeric 
characters. It is useful for such things as sending information 
from a keyboard to the computer, and from one computer to 
another. See Character String Code. 

Assembler: A program that translates assembly-language instruc- 
tions into machine-language instructions. 
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Assembly Language: A machine-oriented language in wliich mne- j 

nnonics are used to represent each nnachine-language instruc- LJ 

tion. Each CPU has its own specific assembly language. See 
CPU and machine language. 



Assignment Statement A BASIC statement that sets a variable, 
constant or array element to a specific numeric or string value. 



u 
u 

Asynchronous Transmission: A scheme in which data characters 

are sent at random time intervals. Limits phone-line transmis- , 

sion to about 2,400 baud (bps). See Synchronous Transmission. ) i 



Attacic: The rate at which the volume of a musical note rises from 
zero to peak volume. 
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Background Color: The color of the portion of the screen that the . , 

characters are placed upon. LJ 

BASIC: Acronym for Beginner's All-purpose Symbolic Instruction , , 

Code. Li 

Baud: Serial-data transmission speed. Originally a telegraph term, , , 

300 baud is approximately equal to a transmission speed of 30 1 i 

bytes or characters per second. 

Binary: A base-2 number system. All numbers are represented as a 1 I 

sequence of zeros and ones. 

Bit: The abbreviation for Binary digIT A bit is the smallest unit in a I [ 

computer. Each binary digit can have one of two values, zero or 

one. A bit is referred to as enabled or "on" if it equals one. A bit | , 

is disabled or "off" if it equals zero. 1 ! 



u 



Bit Control: A means of transmitting serial data in which each bit 
has a significant meaning and a single character is surrounded 
with start and stop bits. 

Bit Map Mode: An advanced graphic mode in the Commodore 1 28 LJ 

in which you can control every dot on the screen. 

Border Colon The color of the edges around the screen. LJ 

Branch: To jump to a section of a program and execute it. GOTO and . 

GOSUB are examples of BASIC branch instructions. LJ 
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Bubble Memory: A relatively new type of computer memory, it uses 
tiny magnetic "pockets" or "bubbles" to store data. 

Burst Mode: A special high speed mode of communication 

between a disk drive and a computer, in which information is 
transmitted at many times normal speed. 

Bus: Parallel lines used to transfer signals between devices. Com- 
puters are often described by their bus structure (i.e., S-1 00-bus 
computers, etc.). 

Bus Network: A system in which all stations or computer devices 
communicate by using a common distribution channel or bus. 

Byte: A group of eight bits that make up the smallest unit of address- 
able storage in a computer. Each memory location in the Com- 
modore 1 28 contains one byte of information. One byte is the 
unit of storage needed to represent one character in memory 
See Bit. 

Carrier Frequency: A constant signal transmitted between commu- 
nicating devices that is modulated to encode binary 
information. 

Character: Any symbol on the computer keyboard that is printed on 
the screen. Characters include numbers, letters, punctuation 
and graphic symbols. 

Character Memory: The area in Commodore 1 28's memory which 
stores the encoded character patterns that are displayed on 
the screen. 

Character Set: A group of related characters. The Commodore 1 28 
character sets consist of: upper-case letters, lower-case letters 
and graphic characters. 

Character String Code: The numeric value assigned to represent a 
Commodore 128 character in the computer's memory 

Chip: A miniature electronic circuit that performs a computer opera- 
tion such as graphics, sound and input/output. 

Cioclc: The timing circuit for a microprocessor. 



389 



GLOSSARY 



Clocking: A technique used to synchronize a sending and a receiv- 
ing data-connnnunications device that is nnodulated to encode 
binary information. 

Coaxial Cable: A transmission medium, usually employed in local 
networks. 

Collision Detection: Determination of occurrence of collision 
between two or more sprites, or between sprites and data. 

Color Memory: The area in the Commodore 1 28's memory that 
controls the color of each location in screen memory 

Command: A BASIC instruction used in direct mode to perform an 
action. See Direct Mode. 

Compiler: A program that translates a high-level language, such as 
BASIC, into machine language. 

Composite Monitor: A device used to provide a 40-column video 
display 

Computer: An electronic, digital device that stores and processes 
information. 

Condition: Expression(s) between the words IF and THEN, evalu- 
ated as either true or false in an IF. . . THEN statement. The 
condition IF. . .THEN statement gives the computer the ability 
to make decisions. 

Coordinate: A single point on a grid having vertical (Y) and horizon- 
tal (X) values. 

Counter: A variable used to keep track of the number of times an 
event has occurred in a program. 

CPU: Acronym for Central Processing Unit. The part of the com- 
puter containing the circuits that control and perform the exe- 
cution of computer instructions. 

Crunch: To minimize the amount of computer memory used to store 
a program. 

Cursor: The flashing square that marks the current location on the 
screen. 
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Data: Numbers, letters or symbols that are input into the computer 
to be processed. 

Data Base: A large amount of data stored in a well-organized man- 
ner. A data-base management system is a program that allows 
access to the information. 

Data Link Layer: A logical portion of data communications control 
that mainly ensures that communication between adjacent 
devices is error free. 

Data Packet: A means of transmitting serial data in an efficient 
package that includes an error-checking sequence. 

Data Rate or Data Transfer Rate: The speed at which data is 
sent to a receiving computer — given in baud, or bits per 
second (bps). 

Datassette: A device used to store programs and data files sequen- 
tially on tape. 

Debug: To correct errors in a program. 

Decay: The rate at which the volume of a musical note decreases 
from its peak value to a mid-range volume called the sustain 
level. See Sustain. 

Decrement: To decrease an index variable or counter by a specific 
value. 

Dedicated Line or Leased Line: A special telephone line arrange- 
ment supplied by the telephone company and required by cer- 
tain computers or terminals, whereby the connection is always 
established. 

Delay Loop: An empty FOR . . . NEXT loop that slows the execution 
of a program. 

Dial-Up Line: The normal switched telephone line that can be used 
as a transmission medium for data communications. 

Digital: Of or relating to the technology of computers and data com- 
munications where all information is encoded as bits of 1 s or Os 
that represent on or off states. 
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Dimension: The property of an array that specifies the direction 
along an axis in which the array elennents are stored. For exam- 
ple, a two-dinnensional array has an X-axis for rows and a Y-axis 
for columns. See Array. 

Direct Connect IVIodem: A device that converts digital signals from 
a computer into electronic impulses for transmission over tele- 
phone lines. Contrast with Acoustic Coupler. 

Direct IVIode: The mode of operation that executes BASIC com- 
mands immediately after the RETURN key is pressed. Also 
called Immediate Mode. See Command. 

Disable: To turn off a bit, byte or specific operation of the computer. 

Disic Drive: A random access, mass-storage device that saves and 
loads files to and from a floppy diskette. 

Disic Operating System: Program used to transfer information to 
and from a disk. Often referred to as a DOS. 

Duration: The length of time a musical note is played. 

Electronic IVIail or E-l\/lail: A communications service for computer 
users where textual messages are sent to a central computer, 
or electronic "mail box," and later retrieved by the addressee. 

Enable: To turn on a bit, byte or specific operation of the computer. 

Envelope Generator: Portion of the Commodore 1 28 that produces 
specific waveforms (sawtooth, triangle, pulse width and noise) 
for musical notes. See Waveform. 

EPROM: A PROM that can be erased by the user, usually by expos- 
ing it to ultraviolet light. See PROM. 

Error Checking or Error Detection: Software routines that identify, 
and often correct, erroneous data. 

Execute: To perform the specified instructions in a command or 
program statement. 

Expression: A combination of constants, variables or array ele- 
ments acted upon by logical, mathematical or relational opera- 
tors that return a numeric value. 
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File: A program or collection of data treated as a unit and stored on 
disk or tape. 

Firmware: Computer instructions stored in ROM, as in a game 
cartridge. 

Frequency: The number of sound waves per second of a tone. The 
frequency corresponds to the pitch of the audible tone. 

Full-Duplex Mode: Allows two computers to transmit and receive 
data at the same time. 

Function: A predefined operation that returns a single value. 

Function Keys: The four keys on the far right of the Commodore 
128 keyboard. Each key can be programmed to execute a 
series of instructions. Since the keys can be SHIFTed, you can 
create eight different sets of instructions. 

GCR Format: The abbreviation for Group Code Recording, a 
method of storing information on a disk in CP/M mode. The 
1541 and 1571 disk drives can read, write and format GCR 
disks. 

Graphics: Visual screen images representing computer data in 
memory (i.e., characters, symbols and pictures). 

Graphic Characters: Non-alphanumeric characters on the comput- 
er's keyboard. 

Grid: A two-dimensional matrix divided into rows and columns. Grids 
are used to design sprites and programmable characters. 

Half-Duplex Mode: Allows transmission in only one direction at a 
time; if one device is sending, the other must simply receive 
data until it's time for it to transmit. 

Hardware: Physical components in a computer system such as 
keyboard, disk drive and printer. 

Hexadecimal: Refers to the base-1 6 number system. Machine lan- 
guage programs are often written in hexadecimal notation. 

Home: The upper-left corner of the screen. 

IC: Integrated Circuit. A silicon chip containing an electric circuit 
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I/O: Input/output. Refers to the process of entering data into the 

computer, or transferring data from the computer to a disk i t 

drive, printer or storage medium. 1 — 1 



made up of components such as transistors, diodes, resistors 
and capacitors. Integrated circuits are smaller, faster and more 
efficient than the individual circuits used in older computers. 

Increment: To increase an index variable or counter with a specified 
value. 

Index: The variable counter within a FOR . . .NEXT loop. 

Input: Data fed into the computer to be processed. Input sources 
include the keyboard, disk drive, Datassette or modem. 

Integer: A whole number (i.e., a number containing no fractional 
part), such as 0, 1,2, etc. 

Interface: The point of meeting between a computer and an exter- 
nal entity, whether an operator, a peripheral device or a com- 
munications medium. An interface may be physical, involving a 
connector, or logical, involving software. 



Keyboard: Input component of a computer system 
Kilobyte (K): 1,024 bytes. 



u 
u 
u 

Loop: A program segment executed repetitively a specified number , j 
of times. \ 1 



Local Network: One of several short-distance data communica- 
tions schemes typified by common use of a transmission 
medium by many devices and high-data speeds. Also called a 
Local Area Network, or LAN. 



Machine Language: The lowest level language the computer under- . 

stands. The computer converts all high-level languages, such i 1 

as BASIC, into machine language before executing any state- 
ments. Machine language is written in binary form that a com- ^ 
puter can execute directly Also called machine code or object LJ 
code. 

Matrix: A two-dimensional rectangle with row and column values. 1 I 

u 
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Memory: Storage locations inside tine connputer. ROiVI and RAM are 
two different types of memory. 

Memory Location: A specific storage address in tine computer. 
Tiiere are 1 31 ,072 memory locations (0-1 31 ,071 ) in the 
Commodore 128. 

MFM: Tlie abbreviation for Modified Frequency Modulation, a 
method of storing information on disks. There are a number of 
different MFM formats used for CP/M programs. The 1571 disk 
drive can read and write to many MFM formats. 

Microprocessor: A CPU that is contained on a single integrated 
circuit (IC). Microprocessors used in Commodore personal 
computers include the 651 0, the 8502 and the Z80. 

Mode: A state of operation. 

Modem: Acronym for MOdulator/DEModulator. A device that trans- 
forms digital signals from the computer into electrical impulses 
for transmission over telephone lines, and does the reverse for 
reception. 

Monitor: A display device resembling a television set but with a 
higher-resolution (sharper) image on the video screen. 

Motherboard: In a bus-oriented system, the board that contains the 
bus lines and edge connectors to accommodate the other 
boards in the system. 

Multi-Color Character Mode: A graphic mode that allows you to 
display four different colors within an 8 X 8 character grid. 

Muiti-Color Bit Map Mode: A graphic mode that allows you to dis- 
play one of four colors for each pixel within an 8 x 8 character 
grid. See Pixel. 

Multiple-Access Network: A flexible system by which every station 
can have access to the network at all times; provisions are 
made for times when two computers decide to transmit at the 
same time. 

Null String: An empty character (" "). A character that is not yet 
assigned a character string code. Produces an illegal quantity 
error if used in a GET statement. 
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Octave: One full series of eight notes on the nnusical scale. 

Operating System: A built-in program that controls everything your 
computer does. 

Operator: A symbol that tells the computer to perform a mathemati- 
cal, logical or relational operation on the specified variables, 
constants or array elements in the expression. The mathemati- 
cal operators are +,-,*,/ and t . The relational operators are 
<,=,>,<=,) = and < >. The logical operators are AND, OR 
NOTandXOR. 

Order of Operations: Sequence in which computations are per- 
formed in a mathematical expression. Also called Heirarchy of 
Operations. 

Parallel Port: A port used for transmission of data one byte at a time 
over multiple wires. 

Parity Bit: A 1 or added to a group of bits that identifies the sum of 
the bits as odd or even. 

Peripheral: Any accessory device attached to the computer such 
as a disk drive, printer, modem or joystick. 

Pitch: The highness or lowness of a tone that is determined by the 
frequency of the sound wave. See Frequency 

Pixel: Computer term for picture element. Each dot on the screen 
that makes up an image is called a pixel. Each character on the 
screen is displayed within an 8 x 8 grid of pixels. The entire 
screen is composed of a 320 x 200 pixel grid. In bit-map 
mode, each pixel corresponds to one bit in the computer's 
memory 

Pointer: A register used to indicate the address of a location in 
memory 

Polling: A communications control method used by some computer/ 
terminal systems whereby a "master" station asks many 
devices attached to a common transmission medium, in turn, 
whether they have information to send. 

Port: A channel through which data is transferred to and from the 
CPU. An 8-bit CPU can address 256 ports. 
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Printer: Peripheral device that outputs the contents of the comput- 
er's memory onto a sheet of paper. This paper is referred to as 
a hard copy. 

Program: A series of instructions that direct the computer to per- 
form a specific task. Programs can be stored on diskette or 
cassette, reside in the computer's memory or be listed on a 
printer. 

Programmable: Capable of being processed with computer 
instructions. 

Program Line: A statement or series of statements preceded by a 
line number in a program. The maximum length of a program 
line on the Commodore 1 28 is 1 60 characters. 

PROM: Acronym for Programmable Read Only Memory A semicon- 
ductor memory whose contents cannot be changed. 

Protocol: The rules under which computers exchange information, 
including the organization of the units of data to be transferred. 

Random Access Memory (RAM): The programmable area of the 
computer's memory that can be read from and written to 
(changed). All RAM locations are equally accessible at any time 
in any order. The contents of RAM are erased when the com- 
puter is turned off. 

Random Number A nine-digit decimal number from 0.000000001 
to 0.999999999 generated by the RaNDom (RND) function. 

Read Only Memory (ROM): The permanent portion of the comput- 
er's memory The contents of ROM locations can be read, but 
not changed. The ROM in the Commodore 1 28 contains the 
BASIC language interpreter, character-image patterns and por- 
tions of the operating system. 

Register: Any memory location in RAM. Each register stores one 
byte. A register can store any value between and 255 in 
binary form. 

Release: The rate at which the volume of a musical note decreases 
from the sustain level to zero. 



f—^^ 
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Remark: Comments used to document a program. Remarks are not 
executed by the computer, but are displayed in tlie program 
listing. 

Resolution: The density of pixels on the screen that determine the 
fineness of detail of a displayed image. 

RGBI Monitor: Red/Green/Blue/lntensity A high-resolution display 
device necessary to produce an 80-column screen format. 

Ribbon Cable: A group of attached parallel wires. 

Ring Network: A system in which all stations are linked to form a 
continuous loop or circle. 

RS-232: A recommended standard for electronic and mechanical 
specifications of serial transmission ports. The Commodore 
1 28 parallel user port can be treated as a serial port if ac- 
cessed through software, sometimes with the addition of an 
interface device. 

Screen: Video display unit which can be either a television or video 
monitor. 

Screen Code: The number assigned to represent a character in 
screen memory When you type a key on the keyboard, the 
screen code for that character is entered into screen memory 
automatically You can also display a character by storing its 
screen code directly into screen memory with the POKE 
command. 

Screen Memory: The area of the Commodore 128's memory that 
contains the information displayed on the video screen. 

Serial Port: A port used for serial transmission of data; bits are 
transmitted one bit after the other over a single wire. 

Serial Transmission: The sending of sequentially ordered data bits. 

Software: Computer programs (sets of instructions) stored on disk, 
tape or cartridge that can be loaded into random access mem- 
ory Software, in essence, tells the computer what to do. 
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Sound Interface Device (SID): The MOS 6581 sound synthesizer 
chip responsible for all the audio features of the Commodore 
1 28. See the Commodore 1 28 Programmer's Reference Guide 
for chip specifications. 

Source Code: A non-executable program written in a high-level lan- 
guage. A compiler or assembler must translate the source code 
into an object code (machine language) that the computer can 
understand. 

Sprite: A programmable, movable, high-resolution graphic image. 
Also called a Movable Object Block (MOB). 

Standard Character Mode: The mode the Commodore 128 oper- 
ates in when you turn it on and when you write programs. 

Start Bit: A bit or group of bits that identifies the beginning of a data 
word. 

Statement: A BASIC instruction contained in a program line. 

Stop Bit: A bit or group of bits that identifies the end of a data word 
and defines the space between data words. 

String: An alphanumeric character or series of characters sur- 
rounded by quotation marks. 

Subroutine: An independent program segment separate from the 
main program that performs a specific task. Subroutines are 
called from the main program with the GOSUB statement and 
must end with a RETURN statement. 

Subscript: A variable or constant that refers to a specific element in 
an array by its position within the array 

Sustain: The midranged volume of a musical note. 

Synchronous Transmission: Data communications using a syn- 
chronizing, or clocking signal between sending and receiving 
devices. 

Syntax: The grammatical rules of a programming language. 
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Variable: A unit of storage representing a clianging string or 

numeric value. Variable names can be any length, but only the [ i 

first two characters are stored by the Commodore 1 28. The first '— ^ 
character must be a letter. 



Tone: An audible sound of specific pitch and waveform. 

Transparent: Describes a computer operation that does not require 
user intervention. 



Video Interface Controller (VIC): The MOS chip (8564/8566) 

responsible for the 40-column graphics features of the Commo- 
dore 128. See the Commodore 128 Programmer's Reference 
Guide for chip specifications. 

Voice: A sound-producing component inside the SID chip. There are 
three voices within the SID chip so the Commodore 1 28 can 
produce three different sounds simultaneously Each voice 
consists of a tone oscillator/waveform generator, an envelope 
generator and an amplitude modulator. 

Waveform: A graphic representation of the shape of a sound wave. 
The waveform determines some of the physical characteristics 
of the sound. 

Word: Number of bits treated as a single unit by the CPU. In an eight- 
bit machine, the word length is eight bits; in a 16-bit machine, 
the word length is 16 bits. 
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381 
ABS function, 70, 307 
Addition, 36 
ADIVI3, 221 
ADSR, 129, 142 
Alt key, 91 
Alt mode, 221 
Animation, 109, 121 
APPEND, 235 
Arrays, 61, 62, 327 
ASC function, 69, 307 
ASCII character codes, 69, 357 
ASM, 197 

Asterisk key (*), 36, 196 , 197 
Attack, 140 
ATN function, 307 
AUTO command, 81, 235 
AUXIN, 213 
AUXOUT, 213 



B 

Bach, 154 

BACKUP, 236 

Bandpass, 149 

BANK, 236 

Bank table, 237 

BAS, 197 

BASIC 

abbreviations, 29 
commands, 233 
functions, 67, 305 
mathematics, 36 
operators, 36 
statements, 233 
variables, 327 

BASIC 2.0, 11, 229 

BASIC 7.0, 5, 229 

BEGIN:/:BEND,77,237 

Binary files, 123 

Bit Map mode, 98 

BLOAD, 123, 238 

BOOT, 239 

Booting, 186 

BOX, 96, 102, 239 

BSAVE, 123, 125, 241 

BUMP, 308 
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C128 Mode, 10 
C64 Mode, 10 
Caps Lock key, 91 
Cartridge Port, 351 
Cartridges, 12 
Cassette Port, 352 
CATALOG, 242 
Channel selector, 353 
CHAR, 96, 104, 242 
Character sets, 21 
Character string code, 69 
CHR$ codes, 357, 367 
CHR$ function, 69, 308 
CIRCLE, 96, 101, 242 
Clock, 328 

CLOSE statement, 177, 245 
CLR, 41, 100, 245 
CLR/HOMEkey,26 
CM D, 245 
COLLECT, 246 
COLLISION, 246 
Colon (:), 52 
COLOR, 96, 97, 247 
Color 

code display chart, 30, 97, 98, 
247 

control, 25„ 34 

CHR$ codes, 357 

keys, 30 

memory map, 361 

screen and border, 99 

source codes, 97 
COM, 188, 197, 198 
Comma (,), 28 
Command, 19 
Command keys, 21 
Command keyword, 188 
Command line, 188 
Command tail, 188 
Commodore key, 25, 26 
Composite monitor, 162 
CONCAT, 248 
CONIN:,213 
CONOUT:, 213 
Constants, 38 

CONTinue command, 71, 248 
Control characters table, 145 
Control key, 25, 185 
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Coordinate grid, 101 


Dual screens, 165 
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COPY, 249 


DUMP, 211 


Copying music, 154 


Duration, 130, 140 




Copying programs, 27, 199 


DVERIFY",46,257 




COPYSYS, 190 




cosine function, 308 






CP/IVI characters, 197 
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CP/IVI mode, 185 


Echo, 203 


CP/M Plus User's Guide, 223 


ED, 193, 211 




CP/IVI Plus 3.0, 185 


Editing, 35, 203 




CTRL-, 188, 204 


EL variable, 328 
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CuRSoRkeys,22,171 


ELSE clause, 77, 267 


Cursor, 21 


END statement, 51, 258 




Cutoff frequency, 148 


Envelope generator, 142 
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ENVELOPE, 142, 258 




Equals ( = ), 39, 52 






ERASE, 210, 211 
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ER/ERR$ variables, 85, 309, 328 


Datassette, 41 


Error functions, 85 




DATA, 59, 250 


Error messages, 337, 343 




Data file, 193 


Escape codes, 370 


— 


DATE, 211 


Escape key, 87, 163, 222 


DCLEAR, 250 


EXIT, 76, 254 




DOLOSE, 250 


Exponentiation, 37 
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Debug, 70, 86 


Exponent function, 309 


DEC, 309 






Decay, 140 




u 


DEFFN,251 


F 


Delay loop, 54 


40/80 Display key, 91, 161 




DELETE, 82, 251 


FAST command, 89, 259 




DELete key, 24 


Features, 9 




DEVICE, 211, 213 


FETCH, 259 




Dice, 68 


File, 193 




DIMension statement, 61, 251 


Filename, 194 


— 


DIR command, 189, 210, 211 


File specification, 193 


Direct mode, 19 


Filetype, 194 




DIRECTORY, 46, 252 


FILE NOT FOUND, 45 


I 


DIRSYS,210 


FILTER, 150, 260 


Disk commands, 43, 177, 385 


Filter— SID, 147 




Disk directory, 42, 46, 179 


Flashing cursor, 88 
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Disk Parameters, 42, 187 


FN function, 309 


Division, 36 


FOR ... NEXT statement, 53, 260 




DLOAD",19,45,253 


FORMAT, 199, 211 




Dollar sign ($), 40, 147, 179, 334 


Formatting disks, 42, 177, 199 
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DO/LOOP, 75, 254 


FRE function, 310 


DOPEN, 255 


Frequency, 130, 138 




DRAW, 96, 102, 255 


Function, 19 


( 


Drive specifier, 194 


Function keys, 27, 89, 172 
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DS/DS$ variables, 328 






DSAVE", 19, 44, 257 
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Game controls and ports, 350 
GET, 57, 211, 212, 261 
GETKEY,80,262 
GET# statement, 263 
G064, 263 
GOSUB,64,263 
GOTO, 33, 264 
GRAPHIC, 96, 99, 264 
Graphic characters, 27 
Graphic modes, 89, 99 
GSHAPE, 297 



LEFTS function, 312 
LENgth function, 312 
LET statement, 270 
Light pen, 12 
Line Feed key, 92 
Line numbers, 31 
LIST command, 32, 270 
LOAD command, 45, 178, 271 
LOADIng cassette software, 178 
LOADIng CP/M software, 186 
LOADIng disk software, 178 
LOCATE, 272 
LOGarithm function, 312 
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Loops, 53 


Harmonics, 138 


LST, 213 


Hash mark (#), 78, 116, 147 




HEADER, 42, 265 




HELP, 83, 90, 211, 214, 267 


M 


HELP key, 90 


Machine language, 371 


HEX, 197 


Mathematics, 36, 363 


HEX$,310 


Memory maps, 360, 361, 365 


HLP, 197 


MID$ function, 312 


HOME key, 26 


Mode switching chart, 13 


Hyperbolic functions, 363 


MONITOR, 273 




Monitor— dual 1902, 14, 163 




Monitor— machine language, 90 
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Monitor switching, 101, 164 


IF. . . THEN Statement, 51, 267 


MOVSPR,116,274 


INITDIR,211 


Multicolor bit mode, 98 


Initializing, 179 


Multiplication, 36 


INPUT, 55, 268 


Music programs, 151, 156 


INPUT#,269 


Music videos, 153 


Input Prompt, 56 


Musical notes, 144 


INSerT key, 24 


Musical instruments, 142 


INSTR,310 


Musical scale, 154 


INTeger function, 67, 311 
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N 


JOY, 311 


Nested loops, 54 


Joystick ports, 350 


NEW, 34, 275 




NEXT statement, 53, 260 
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Noise, 139 


No Scroll key, 91 


KEY command, 90, 269 


Notch Reject Filter, 153 


Keyboard, 20 


Notes, 144 


Key assignment— CP/M, 220 


Numeric functions, 67 
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Object code file, 123 


RAM, 65, 


ONGOTO/GOSUB,65,275 


Random sounds, 136 




OPEN statement, 177, 275 


ROLR, 315 


..^ 


Operating System, 185 


ROOT, 316 


Operators 


READ, 59, 285 




aritlimetic, 36, 329 


RECORD, 286 




logicai, 329 


Relational operators, 52 


order of, 37 


REL, 197 




relational, 52, 329 


Release, 140 






REMark statement, 28, 287 






RENAME, 210, 211, 287 
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RENUMBER, 81, 288 




PAINT, 96, 103, 277 


Reset button, 161 
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Parentheses, 38, 197 


Reserved variables, 328 


Password, 195 


Rest, 144 




PEEK function, 66, 313 


Restore key, 26 




PEN, 313 


RESTORE statement, 60, 289 


PERFECT series software, 5 


RESUME command, 84, 289 




Period (.), 147 


Return key, 21 




PI, 334 


RETURN statement, 64, 290 


PIP, 193, 199, 211 


RGBI monitor, 163 




Pixel, 98, 114 


RGBI port, 162, 354 




PLAY, 143, 278 


RGR,316 


— 


POINTER, 314 


RIGHTS function, 316 


POKE, 66, 280 


RND function, 68, 136, 317 




POS function, 314 


RSPCOLOR,317 
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POT, 315 


RSPPOS, 318 


Pound symbol (#)— see Hash 


RSPRITE, 318 




mark 


RUN command, 32, 290 




PRINT, 28, 280 


RUN/STOP key, 25, 100, 136, 144, 


PRINT USING, 78, 282 


161 




PRINT#,177,281 


RWINDOW,319 




Printer control— CP/M, 203 
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PRN, 197 


s 


Program file, 193 


SAVE command, 44, 176, 291 




Program mode, 19 


Saving programs on tape, 178 


•^ 


Programmable keys, 172 


Saving programs on disk, 176 


Programming aids, 81 


Sawtooth waveform, 139 




Programmer's Reference Guide, 6 


SCALE, 104, 292 




PUDEF, 79, 285 


SCRATCH command, 293 


Pulse width, 134, 141 


SCNCLR command, 89, 293 




PUT, 211, 212 


Screen display codes, 355 






Screen display, 98, 161 




Screen memory map, 361 




Q 


Scrolling, 88 




Question mark (?), 29, 196 


Sector, 42 


■ — 


Quotation marks ("), 29 


Semicolon (;), 29 


Quote mode, 31 


Serial port, 352 
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SET, 211 

SETDEF, 203, 211 

SGN function, 320 

SSHAPE, 96, 111, 297 

Sharps (#), 147 

Sheet music, 154 

Shift key, 22 

SHOW, 211 

SID chip, 129 

SINe function, 320 

Slash [<ey(/), 36 

SLEEP, 78, 293 

SLOW command, 89, 294 

Software— 80 column, 165 

SOUND, 133, 294 

Sound Interface Device, 129 

Sound Player Program, 135 

Sound reset, 136, 144 

SPC function, 320 

Split screen display, 98 

SPRCOLOR, 295 

SPRDEF,96,109,295 

SPRITE, 96, 115, 296 

Sprite Combinations, 119 

Sprite control, 115 

Sprite editor, 110 

Sprite programming, 109, 118 

Sprite memory map, 125 

Sprite movement, 116 

Sprite viewing area, 117 

Sprites, 108 

SPRSAV, 96, 115, 297 

SQR function, 321 

ST variable, 328 

STASH, 300 

Statement, 19, 31 

STEP, 260 

STOP, 300 

STOP key, 25 

Storing programs, 175 

String functions, 67 

Strings, 29, 40 

STR$ function, 321 

SUB, 197 

SUBMIT, 211 

Subroutine, 64 

Subscripts, 61 

Subtraction, 36 

Sustain, 140 



SWAP, 300 
Sweep, 131 
Syntax, 19 
Syntax error, 22 
Synthesizer, 129, 145 
SYM, 197 
SYS, 197, 300 
System prompt, 187 



T 

Tab key, 92 

TAB function, 321 

TAB stops, 88 

TANgent function, 322 

TEMPO, 143, 301 

Terminating CP/M, 214 

THEN, 51, 267 

Timbre, 138 

Time delay, 54 

TI/TI$ variables, 328 

TO, 102, 260 

Track, 42 

Transient Utility commands, 188, 

210 
TRAP, 83, 301 
Triangle waveform, 139 
Trigonometric functions, 363 
TRON/TROFF,85,302 
TYPE command, 210, 211 
Typing rules, 27 
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UNTIL statement, 75, 254 

Up arrow (t) key, 37 

Upper case/graphic set, 21, 171 

Upper/Lower case set, 21, 171 

USER, 195, 210 

User Number, 195 

User port, 354 

USR function, 322 



VALue function, 70, 322 
Variables, 39, 61, 327 
VERIFY command, 46, 179, 302 
VIC chip, 95 



405 



INDEX 



Video Ports, 162, 353 

Voice, 129 

VOLume, 132, 143, 303 



W 

WAIT command, 303 

Waveform, 129, 139, 141 

WHILE statement, 76, 254 

WIDTH, 304 

Wildcard, 196 

WINDOW command, 86, 304 

Windowing, 86 

X 

XOR, 323 



Z80 Microprocessor, 185 
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COMMODORES 

WOULD YOU LIKE TO DO MORE WITH 
CP/M® ON YOUR COMMODORE 128? 

Digital Research Inc. (DRI) and Commodore have arranged for additional CP/M 
documentation to be made available to you. DRI's complete CP M Plus Version 
3.0 users manual, consisting of User's Guide, Programmers Reference Guide, 
and System Guide can be yours for $19.95 ($29.95 for Canadian residents). You 
will also receive two utility disks not included with your Commodore 128, 

Complete the order form below, tear off and return to appropriate address. Retain this top 
portion for your records. 



Date mailed: 



Please allow 6 to 8 weeks for delivery. 



Y6S5 I would like to receive the complete Digital Research inc. user documentation for CP/M 
and the two CP M utility disks. 

Enclosed is my payment of $19.95 ($29.95 if Canadian resident)* per order. 

D Check D Money Order 

(Do not send cash) 

•Residents of Pennsylvania add 6% sales tax, residents of Ontario add 7% sales tax. 



NAME_ 



ADDRESS 



CITY, STATE OR PROVINCE. 



_2IP OR POSTAL CODE. 



PHONE NUMBER^L 



Return to: 

In the U.S. 

(Payable to Commodore Direct Marketing) 

Commodore Direct Marketing 

DRI Offer 

C-2651 

West Chester, Pennsylvania 19380 



In CANADA 
(Payable to Commodore Business Machines, Ltd.) 

National Fulfillment 

DRI Offer 

3470 Pharmacy Ave. 

Agincourt, Ontario, Canada M1 W 3G3 



Please allow 6 to 8 weeks for delivery. 

CP/M is a Registered Trademark of Digital Researcti Inc. 
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